Skip to content

Commit 78a8388

Browse files
fix(scenarios): judge the bare-name Build check only where ADR-0150 keeps the literal prefix (#31749)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} --> _Requested by **Steedos** · [project thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbCPAmC6XoinFYKSk7wgQt4T)_ Fixes #31729 Clause-②: no Metadata-protocol: none ## 维护者速读 - **改了什么**:场景评分器的 `bare-name` 构建检查只再判视图、文档、岗位(`NS_SHORT`)和能力(`NS.SHORT`);流程、动作、作业、工具、仪表盘、权限集等行为元数据裸名不再判失败;构建与迭代提示词的命名规则同步收窄。 - **为什么改**:ADR-0150 已把 bucket 2–4 类型改为按(软件包, 名称)寻址,忠实按新规则命名的应用不应在评分和画廊导出时被判构建失败;须与 #31669(child P,撤销 lint 与技能文案)同时或更早落地,避免评分器、技能、模板教出两套规则。 - **风险与回滚**:只影响评分规则与提示词文本,不动任何平台解析或 spec;回滚即 revert 本 PR。能力名写成 `NS_SHORT` 现在会判失败(此前通过),与 ADR-0150 D1 的 `NS.SHORT` 拼写一致。 - **先看**:`packages/qa/scenarios/src/score/scenario-naming.ts`(判哪些类型、能力的点号前缀);`packages/qa/scenarios/test/score/entry.test.ts` 末段(读取 ADR-0150 D1 表格的钉子测试);`packages/qa/scenarios/src/runner/prompts.ts` 的 `namingRule`。 - **两分钟验证**:`pnpm --filter @objectstack/scenarios exec vitest run test/score/entry.test.ts`,预期 14 个用例全绿,其中裸流程/动作/工具/作业通过、裸岗位/视图失败、无 `NS.SHORT` 的能力失败。 - **需要你做的**:无,席位落地。 ## What changes - `gradeItemNames` (`src/score/scenario-naming.ts`) judges only the manifest collections that hold a type ADR-0150 keeps on the global literal prefix: D1's bucket 1 (`object`, `field`, `object_extension`, `view`, `capability`, `doc`) and the position (D7, one environment-wide slot per name). Of the collections the scorer walks that is views, docs and positions, named `NS_SHORT`, and capabilities, named `NS.SHORT`. Objects stay out (`defineStack` judges them); an api item's `name` is bucket 2 and passes. Every other bare name (flow, action, job, tool, skill, agent, app, page, dashboard, permission set, …) is no finding. - **Where the bucket list comes from.** Child P (#31669) has no PR open and its branch (`b7acc113`) exports no per-type bucket from the platform; its list is cli-local. So the list is restated from ADR-0150 D1's table in a comment and a module-private constant, and `test/score/entry.test.ts` reads the ADR's bucket-1 and position rows and fails when either row changes, or when the types the check judges stop being exactly the rows' types the manifest walks. Once P (or R) exports the bucket of each type, the constant moves to read it, tracked on #31669. Nothing new is exported from `./score`. - `namingRule` (`src/runner/prompts.ts`), used by the build, iterate and template-iterate prompts, asks for `NS_` on objects, views, docs and positions and `NS.` on capabilities, says every other item needs no prefix, and keeps "where this prompt names an item, use that exact name" so the stated names (persona permission sets, dashboards, agent actions) still match the Build half's exact-name checks. - Prose this makes false is corrected (claim amendment 6730010093): the `namespace.ts` and `scenarioNamespace` docblocks, the `naming` field docblock in `scenario-tags.ts`, and README's Namespaces bullet. `namespace.ts` still prefixes the card's own names, so the prompt and the Build half keep one spelling. - The ADR file the pin reads is declared as a scenarios test input (claim amendments 6730243476 and 6730537694): `scripts/cross-package-test-inputs.mjs` (the `@objectstack/scenarios` globs), root `turbo.json` (`@objectstack/scenarios#test` inputs), and `scripts/check-ci-filter-parity.mjs`, whose rollback pin counts declared globs under the `docs/**` root (22 → 23, recorded by name). - Changeset `31729-scenario-naming-literal-prefix.md`, `patch` on `@objectstack/scenarios` (published). ## Tests - `test/score/entry.test.ts`: a bare flow, action, tool, job, dashboard, permission set and api name pass; a bare position, view and doc fail, and a capability spelled `export_data` or `democrm_export_data` fails while `democrm.refund` passes, each one counted check; the ADR-0150 D1 pin; the multi-package case now finds a bare view under `packages[]`. - `test/runner/orchestrate.test.ts`: the bare-items build now yields only the view finding (build and iterate build); the bare dashboard is no finding. - `test/runner/units.test.ts`: every authoring prompt states the narrowed rule and no longer says "EVERY metadata item". ## Acceptance notes - Serial with #31669: P has no PR yet. `git merge-tree --write-tree` of head `edb1f41b` against P's branch head `b7acc113` is clean, and the two diffs share no file. - ADR-0150 D9's hand-off line is executed as written: view, doc and capability keep the check, plus positions. ## Verification <details><summary>Local runs (code at head 805f90e; 947b040 adds only the changeset)</summary> - `pnpm --filter @objectstack/scenarios build && … test && … typecheck` under the verify lock: build ok, Test Files 31 passed (31), Tests 618 passed (618), typecheck exit 0 (`tsc --listFiles` includes the three edited test files). - Ablations, each through `scripts/ablation-replace.mjs`, restored to the HEAD blob after: (1) judging every collection again: 4 tests red (bucket 2-4 pass, ADR pin, multi-package, orchestrate); (2) capability prefix `NS_` instead of `NS.`: the position/view/doc/capability test red; (3) adding `` `dashboard` `` to the ADR-0150 D1 bucket-1 row: the ADR pin red. - Derived gates (`dispatch-gates --commands`, 82 families on the final tree, code at `8b3f7e4e`/`edb1f41b`): 81 exit 0, reconciled with `--ran` (0 unrun). `check:dual-build-cjs-loads` is NOT MEASURED locally (exit 3, needs a full workspace build), left to CI. `check-plugin-teardown-shape --self-test` exit 0 after fetching its pinned fixture. `check:pm-dispatch-gates` exit 0 (2205 cases). `check:cross-package-test-inputs` and `check:ci-filter-parity` were red before the input declarations and exit 0 after. - `origin/main` (`0105a687` and three more) merged at `edb1f41b`; it touches none of this PR's files, so nothing above was re-run. </details> --- _Generated by [Claude Code](https://claude.ai/code/session_01QsR2jSUNgKkrn9jFYL5BWj)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3dc33c5 commit 78a8388

13 files changed

Lines changed: 179 additions & 62 deletions
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/scenarios': patch
3+
---
4+
5+
fix(scenarios): the scorer's bare-name Build check judges only the names ADR-0150 keeps on the literal prefix, and the build prompt asks for the prefix only there
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The scorer (`gradeItemNames`, `./score`) used to fail every non-object item a build named without the app's namespace, and the build and iterate prompts told the agent to prefix every item. ADR-0150 identifies flows, actions, jobs, tools, skills, agents, apps, pages, dashboards, permission sets and every other behavioural type by (package, name), so a build that names them plainly is correct.
11+
12+
- **Judged now:** views, docs and positions named `<namespace>_<short>`, and capabilities named `<namespace>.<short>`. A bare one is still a failing Build check `bare-name:<type>:<name>`, and a capability spelled `<namespace>_<short>` now fails too. Objects stay judged by `defineStack`.
13+
- **No longer judged:** every other collection. A build whose only finding was a bare flow, action, dashboard or permission set name now passes its Build half.
14+
- **Prompts:** the naming rule names the prefixed types and says every other item needs no prefix, while the names the prompt states (persona permission sets, dashboards, agent actions) are still used exactly.

‎packages/qa/scenarios/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -250,8 +250,8 @@ npx @objectstack/scenarios help # the comma
250250
mode scaffolds the project under that name, and template mode installs a template declaring it into a host named
251251
`host<code>` (the unmanaged copy keeps its namespace, and the install refuses one the host owns). The card's names are
252252
read relative to it (`account` → `democrm_account`), because a scaffolded project and the unmanaged install both
253-
refuse bare object names. The build prompt asks for the prefix on EVERY item, and the scorer reports each bare
254-
non-object item name as a failing Build check (`bare-name:<type>:<name>`), so such a build is never verified.
253+
refuse bare object names. Views, docs, positions and capabilities (`<ns>.<short>`) keep the prefix too (ADR-0150 bucket 1 and
254+
D7): the scorer reports each bare one as a failing Build check (`bare-name:<type>:<name>`); other items may be bare.
255255
- **Persona contract**: the build is asked for one permission set per persona, named `<namespace>_<persona id>`. The runner
256256
grants it to that persona's user, and loads a seed row as owned (`owner_id`) by a persona's user only when the row
257257
names that person (`rowOwner` in `prompts.ts`): it IS the persona's `record`, a declared direct lookup on it holds

‎packages/qa/scenarios/src/runner/namespace.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,10 @@
1616
* `democrm`), in both modes, so a scored build's names are the same on every
1717
* run and every machine. The card's object `account` is `democrm_account` — in
1818
* `expect`, the seed, its user-handle fields, questions, personas (with their
19-
* person records), operations, guardrails and the iterate delta. Every other item the card names carries the prefix too, since
20-
* a gallery app prefixes every item name (the scorer reports a bare one,
21-
* `score/scenario-naming.ts`): the expected dashboards and nav targets, the
22-
* agent actions, and each persona's permission set ({@link permissionSetName}).
19+
* person records), operations, guardrails and the iterate delta. Every other item the card names carries the prefix too, so
20+
* the names the prompt states and the Build half checks are one spelling on every run: the
21+
* expected dashboards and nav targets, the agent actions, and each persona's permission
22+
* set ({@link permissionSetName}). The scorer requires it only where ADR-0150 does.
2323
* Fields, row ids, persona ids and computed truths are untouched (a truth is
2424
* keyed by question id and computed over row values). An answer may still cite
2525
* the bare object name: {@link citationLabels} hands the grader both spellings.

‎packages/qa/scenarios/src/runner/prompts.ts‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,12 @@
1818
* - the reference cycles the seed's lookups close (`seed.ts`), when there
1919
* are any: the runner loads them in two passes, so at least one side of
2020
* each must be optional;
21-
* - the naming rule: EVERY item the app declares is named
22-
* `<namespace>_<short>`, not only its objects ({@link namingRule}). The
23-
* scorer reports a bare one as a Build finding, so every authoring prompt
24-
* (build, iterate, template iterate) states it;
21+
* - the naming rule ({@link namingRule}): the items whose names stay
22+
* global in the environment carry the namespace (objects, views, docs and
23+
* positions `<namespace>_<short>`, capabilities `<namespace>.<short>`),
24+
* and every other item is named plainly (ADR-0150 D1, D7, D9). The scorer
25+
* reports a bare one of the first kind as a Build finding, so every
26+
* authoring prompt (build, iterate, template iterate) states it;
2527
* - the structure the Build half checks by exact name beyond the seed
2628
* ({@link structureLines}): each lookup's target, each single-choice field
2729
* with its minimum option count, each dashboard and each app navigation
@@ -199,13 +201,19 @@ export function unheldHandles(card: Card): string[] {
199201
return [...out].sort();
200202
}
201203

202-
/** The every-item-prefixed rule, in every authoring prompt. */
204+
/**
205+
* The naming rule, in every authoring prompt: the items the scorer judges
206+
* (`score/scenario-naming.ts`, ADR-0150 bucket 1 and positions) carry the
207+
* namespace, and the rest are addressed by their package and named plainly.
208+
*/
203209
export function namingRule(card: Card): string {
204210
const ns = scenarioNamespace(card);
205211
return (
206-
`Naming: this app's namespace is \`${ns}\`. Name EVERY metadata item you declare \`${ns}_<name>\` — not only objects, ` +
207-
'but also views, apps, pages, dashboards, reports, datasets, actions, flows, permission sets, picklists, skills, agents ' +
208-
'and every other item. Fields are not items and keep their plain names. A bare item name fails the build.'
212+
`Naming: this app's namespace is \`${ns}\`. Name each object, view, doc and position you declare \`${ns}_<name>\`, ` +
213+
`and each capability \`${ns}.<name>\`: these names are global in the environment, and a bare one fails the build. ` +
214+
'Every other item (apps, pages, dashboards, reports, datasets, actions, flows, jobs, permission sets, picklists, tools, ' +
215+
'skills, agents and the rest) belongs to this package and needs no prefix, but where this prompt names an item, use ' +
216+
'that exact name. Fields are not items and keep their plain names.'
209217
);
210218
}
211219

‎packages/qa/scenarios/src/schema.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -517,9 +517,9 @@ export const SCENARIO_NAMESPACE_PREFIX = 'demo';
517517

518518
/**
519519
* The namespace a card's app lives in, wherever it is built, scored or
520-
* exported: `demo` + the card's code (`democrm`). Every item the app declares
521-
* is named `<namespace>_<short>`, and the card's own names (`account`) are read
522-
* relative to it (ruling A on #30292).
520+
* exported: `demo` + the card's code (`democrm`). Its objects, views, docs and
521+
* positions are named `<namespace>_<short>`, and the card's own names (`account`)
522+
* are read relative to it (ruling A on #30292).
523523
*/
524524
export function scenarioNamespace(card: { code: string }): string {
525525
return `${SCENARIO_NAMESPACE_PREFIX}${card.code}`;

‎packages/qa/scenarios/src/score/scenario-naming.ts‎

Lines changed: 48 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,35 @@
11
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
22

33
/**
4-
* The every-item-prefixed rule of a gallery app: each item a scenario app
5-
* declares is named `<namespace>_<short>` (`democrm_pipeline`), not only its
6-
* objects. Two gallery apps installed in one environment then cannot collide on
7-
* a bare name (`overview`, `sales_manager`), and a gallery app reads as one.
4+
* The literal-prefix rule of a gallery app: an item whose name stays global
5+
* in the environment carries the app's namespace, so two gallery apps
6+
* installed in one environment cannot collide on it.
87
*
9-
* Objects are not judged here: `defineStack` already refuses an object without
10-
* its namespace prefix, and the card's `expect` names them namespace-relative.
11-
* Every OTHER collection of the manifest is, as the spec spells them
12-
* (`PLURAL_TO_SINGULAR`, the one table of manifest collections), read through
13-
* `resolveStackCollection` so a multi-package artifact is judged too.
8+
* Which names stay global is ADR-0150's, not this file's. Its D1 table keeps
9+
* bucket 1 on the global literal prefix:
10+
*
11+
* `object` (ADR-0129 D2, the table name) · `field` · `object_extension` ·
12+
* `view` (object-derived) · `capability` (`NS.SHORT`, ruling 6683456244) ·
13+
* `doc` (ADR-0046 doc lint) · an api's `path` (globally unique)
14+
*
15+
* and D7 keeps a `position` as one slot per name in the environment, so a
16+
* bare position still collides at install. Every other type (buckets 2-4:
17+
* flows, actions, jobs, tools, skills, agents, apps, pages, dashboards,
18+
* permission sets, an api item's `name`, …) is identified by (package, name)
19+
* and is named plainly: ADR-0150 D9 narrows this check to bucket 1 and
20+
* positions. {@link LITERAL_PREFIX_TYPES} restates that table until the
21+
* platform exports the bucket of each type; `test/score/entry.test.ts` reads
22+
* the ADR's two rows, and fails when they change or when the types this check
23+
* judges stop being exactly the ones they name.
24+
*
25+
* Of the manifest collections (`PLURAL_TO_SINGULAR`, the one table of them,
26+
* read through `resolveStackCollection` so a multi-package artifact is judged
27+
* too), four hold such a type: views, docs and positions, named
28+
* `<namespace>_<short>`, and capabilities, named `<namespace>.<short>`
29+
* ({@link literalPrefix}). Objects are not judged here: `defineStack` already
30+
* refuses an object without its namespace prefix, and the card's `expect`
31+
* names them namespace-relative. Fields and object extensions are not
32+
* collections of the manifest, and an api's `path` is not its name.
1433
*
1534
* Only a bare name produces a check, and it always fails: one Build finding
1635
* per item, named by its type and name, so a candidate with one fails the
@@ -24,16 +43,31 @@ import { PLURAL_TO_SINGULAR } from '@objectstack/spec/meta-spelling';
2443

2544
import type { CheckResult } from './scenario-score.js';
2645

27-
/** One failing check per non-object item of `artifact` whose name does not start `<namespace>_`. */
46+
/**
47+
* The metadata types whose name keeps the global literal prefix: ADR-0150 D1's
48+
* bucket 1 and the position (D7), restated from the ADR's table.
49+
*/
50+
const LITERAL_PREFIX_TYPES: readonly string[] = Object.freeze(['object', 'field', 'object_extension', 'view', 'capability', 'doc', 'position']);
51+
52+
/** The manifest collections this check walks (plural key → type): those of {@link LITERAL_PREFIX_TYPES}, objects excepted. */
53+
const PREFIX_JUDGED_COLLECTIONS: Readonly<Record<string, string>> = Object.freeze(
54+
Object.fromEntries(Object.entries(PLURAL_TO_SINGULAR).filter(([key, type]) => key !== 'objects' && LITERAL_PREFIX_TYPES.includes(type))),
55+
);
56+
57+
/** What a `type` item's name starts with in an app of `namespace`: `<namespace>.` for a capability (`NS.SHORT`), else `<namespace>_`. */
58+
function literalPrefix(type: string, namespace: string): string {
59+
return type === 'capability' ? `${namespace}.` : `${namespace}_`;
60+
}
61+
62+
/** One failing check per item of `artifact` that keeps the literal prefix (views, docs, capabilities, positions) and is named without it. */
2863
export function gradeItemNames(artifact: unknown, namespace: string): CheckResult[] {
29-
const prefix = `${namespace}_`;
3064
const out: CheckResult[] = [];
31-
for (const [key, type] of Object.entries(PLURAL_TO_SINGULAR)) {
32-
if (key === 'objects') continue;
65+
for (const [key, type] of Object.entries(PREFIX_JUDGED_COLLECTIONS)) {
66+
const prefix = literalPrefix(type, namespace);
3367
for (const item of resolveStackCollection(artifact, key)) {
3468
const name = typeof item === 'object' && item !== null ? (item as { name?: unknown }).name : undefined;
3569
if (typeof name !== 'string' || name.startsWith(prefix)) continue;
36-
out.push({ check: `bare-name:${type}:${name}`, pass: false, detail: `a gallery app names every item \`${prefix}<short>\`; this ${type} is \`${name}\`` });
70+
out.push({ check: `bare-name:${type}:${name}`, pass: false, detail: `a gallery app names each ${type} \`${prefix}<short>\`; this ${type} is \`${name}\`` });
3771
}
3872
}
3973
return out;

‎packages/qa/scenarios/src/score/scenario-tags.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -888,7 +888,7 @@ export interface ScenarioArtifactScore {
888888
shape: ScoreResult;
889889
tags: TagVerdict[];
890890
agentActions: CheckResult[];
891-
/** One failing check per bare non-object item name ({@link gradeItemNames}); empty when no namespace was given. */
891+
/** One failing check per bare view, doc, capability or position name ({@link gradeItemNames}); empty when no namespace was given. */
892892
naming: CheckResult[];
893893
/** Checks passed across `expect`, the scored tags, the agent actions and the naming rule. */
894894
passed: number;

‎packages/qa/scenarios/test/runner/orchestrate.test.ts‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -412,18 +412,16 @@ describe('runCard — the card’s own namespace, demo + code', () => {
412412
expect(ops.scaffolded).toEqual([]);
413413
});
414414

415-
it('a build naming a non-object item bare fails its Build half: one finding per item, and it is never verified', async () => {
415+
it('a build naming a view bare fails its Build half, and is never verified; its bare dashboard is no finding (ADR-0150)', async () => {
416416
const { scenario, ops, driver } = setup({ bareItems: true });
417417
const run = await runCard(scenario, driver, ops, { modes: ['scratch', 'template'], admin: ADMIN, iterateRun: false });
418418
const sc = cardScorecard(run);
419419
expect(run.modes[0]!.build!.score!.expect.checks.every((c) => c.pass)).toBe(true); // every expected name is there…
420-
expect(run.modes[0]!.build!.score!.naming.map((c) => c.check)).toEqual(['bare-name:dashboard:overview', 'bare-name:view:all_accounts']);
420+
expect(run.modes[0]!.build!.score!.naming.map((c) => c.check)).toEqual(['bare-name:view:all_accounts']);
421421
expect(sc.modes[0]!.first.build!.degraded).toBe(true); // …and the build still fails
422422
expect(sc.modes[1]!.skipped).toMatch(/no verified build/);
423423
expect(sc.modes[0]!.findings).toEqual([
424-
expect.stringMatching(/^build: bare item name dashboard overview \(.*`democrm_<short>`/),
425-
expect.stringMatching(/^build: bare item name view all_accounts /),
426-
expect.stringMatching(/^iterate build: bare item name dashboard overview /),
424+
expect.stringMatching(/^build: bare item name view all_accounts \(.*`democrm_<short>`/),
427425
expect.stringMatching(/^iterate build: bare item name view all_accounts /),
428426
]);
429427
expect(renderScorecard(sc)).toContain('- scratch finding: build: bare item name view all_accounts');

‎packages/qa/scenarios/test/runner/units.test.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -414,12 +414,13 @@ describe('prompts, seed order, template manifest and change size', () => {
414414
expect(questionPrompt(crm, 'tech_accounts')).toMatch(/^How many accounts are in tech\?/);
415415
});
416416

417-
it('every authoring prompt states the every-item-prefixed rule, and the contract names every item prefixed', () => {
417+
it('every authoring prompt states the literal-prefix rule for the types the scorer judges, and the contract names every item prefixed', () => {
418418
const card = namespacedScenario(crm).card;
419419
const server = { baseUrl: 'http://x', adminEmail: 'a@x', adminPassword: 'p' };
420420
for (const p of [buildPrompt(card), iteratePrompt(card), templateIteratePrompt(card, server)]) {
421-
expect(p).toContain("Naming: this app's namespace is `democrm`. Name EVERY metadata item you declare `democrm_<name>`");
422-
expect(p).toMatch(/not only objects, but also views, apps, .*dashboards.*permission sets/);
421+
expect(p).toContain("Naming: this app's namespace is `democrm`. Name each object, view, doc and position you declare `democrm_<name>`, and each capability `democrm.<name>`");
422+
expect(p).toMatch(/Every other item \(apps, .*dashboards, .*actions, flows, jobs, permission sets, .*tools, skills, agents and the rest\) belongs to this package and needs no prefix/);
423+
expect(p).not.toMatch(/EVERY metadata item/);
423424
}
424425
const contract = dataContract(card);
425426
expect(contract).toContain('- `democrm_delete_contact` on `democrm_contact`');

0 commit comments

Comments
 (0)