fix(create-objectstack,cli): starter objects place their fields in a keyed field group

[objectstack-fleet]

Fixes #21370
Clause-②: no

What changes

Each starter object now places the fields it declares in a keyed field group (fieldGroups on the object, group on each field, ADR-0085 §5), as triage ruled in comment 5948728426:

• packages/create-objectstack/src/templates/blank/src/objects/note.object.ts (npm create objectstack): fieldGroups: [{ key: 'details', label: 'Details' }], with group: 'details' on title and body.
• packages/cli/src/commands/init.ts, TEMPLATES.app (os init -t app): the same group, on name, description and status.

Each object carries a comment for the author. It says what the group does, that it is what displays the field, that objectstack validate / objectstack lint report a field nothing displays or reads once the project holds anything that could read it, and that a new field should name a group too. It links the public page on field groups. field-no-consumers itself is unchanged: there is no starter carve-out, no field was dropped, and nothing in packages/lint was edited. The rule already credits a field the synthesized layout places in a keyed section as displayed.

Clause-② is no, measured against the diff: the templates gain placement keys the schema already accepts, and no accept set or public member moves. The changeset (.changeset/21370-starter-field-groups.md) is a patch for create-objectstack and @objectstack/cli, the two packages whose shipped templates change.

Measured before and after, through the real commands

Before, at origin/main 69a12a0: one fresh project per starter and per waker, then os validate --json and os lint --json. Each cell is the field-no-consumers count, identical under both commands, every command exit 0.

starter	bare	os g dashboard probe	os g object gate_target + os g view gate_target	os g object gate_target + os g flow gate_probe --object gate_target
npm create objectstack	0	1: body	1: body	1: body
os init -t app	0	2: description, status	2	2
os init -t plugin	0	0	0	0

os init -t plugin is clean because its only field is the record's title, which the rule exempts through the nameField ladder. os init -t empty declares no object. Neither template changes.

After, at d94a0d6: the nightly pin below runs each starter, then all three wakers in one project. It reads 0 field-no-consumers under both commands for all three starters. With the starters' group lines stripped, both commands report the finding again, on the starters' own fields only.

Pins

• packages/cli/test/starter-field-consumers.test.ts: per-PR, unit tier, in-process. The roster is derived: every *.object.ts the blank starter ships and every one an os init template renders. Each source is loaded the way os validate loads it (bundle-require with BUNDLE_REQUIRE_EXTERNALS). Each starter is combined with the real dashboard, view and flow generator output, the latter two bound through stackBindingCandidates to an object generated beside the starter's. Each stack is run through runAuthoringRules('validate') and lintConfig, with zero field-no-consumers asserted (9 legs). CONTROL: every non-title starter field, with its group removed, is reported at exactly its own path by both commands (3 legs: body, description, status). The title is read through resolveDisplayField, not restated. Every leg also requires its stack to pass defineStack and parse, so a pipeline that stopped early cannot read as a zero.
• packages/cli/test/starter-field-consumers.e2e.test.ts: nightly, real commands. Starters: the on-ramp's bin/, plus every os init -t template that renders an object. Each runs os g dashboard, os g object, os g view and os g flow, then os validate --json and os lint --json, and must report zero field-no-consumers (6 legs). CONTROL: every group line stripped from the scaffolded objects, then the same two commands must report the finding, only on fields the stripped files declare (4 legs). It runs only for starters whose sources place a field, which is decided when the file is collected.
• packages/cli/test/generate-scaffold-gates.e2e.test.ts: the one STARTER_LATENT_FINDINGS entry (field-no-consumers@objects[0].fields.body) is deleted, so the ledger is empty. The header now records why. The ledger's describe gains a floor test pinning it empty. Without that test the block would hold no test at all once both it.each tables are empty, and vitest 4 fails such a block with "No test found in suite".

Red before the fix, and the ablations

All ablations ran from the committed fix (d94a0d6) through scripts/ablation-replace.mjs: the anchor hit once, the mutation was proven on disk, and the restore was proven as blob == HEAD with git diff HEAD empty. Dist-mediated legs were rebuilt and read with scripts/ablation-dist-preflight.mjs.

• Red before the fix. The in-process pin ran against the 69a12a0 templates (git restore --source=69a12a0952, tree only). Result: 8 failed, 6 passed. The 3 blank and 3 app waker legs failed (objects[0].fields.body; description + status), and so did the 2 app controls (both fields reported, not one). Plugin and the blank control passed, as expected. Restored: blob == HEAD for both files.
• A1, blank body loses its group: 3 failed, 11 passed. Exactly the 3 blank waker legs.
• A2, app description loses its group: 4 failed, 10 passed. The 3 app waker legs, plus the status control.
• A3, the rule credits the untitled bucket (if (section.key === undefined) continue; deleted, @objectstack/lint rebuilt; preflight --absent with --source-marker passed): 3 failed, 11 passed. Exactly the 3 control legs. Restore leg: lint rebuilt, and the marker section.key === void 0 is present again in dist.
• E (nightly pin), blank body and app description lose their groups. create-objectstack and @objectstack/cli were rebuilt, and the dist read group: 'details' 2 → 1 and 3 → 2, with the plant marker present 1 / 1. Result: 4 failed, 11 passed. Exactly the blank and app zero legs under os validate and os lint. Restore leg: both rebuilt, counts back to 2 / 3, markers 0 / 0.
• EC (nightly control), the same A3 guard deletion: 15 passed, so it did not red the nightly control. That is expected on reading: the control strips every group, title included, so deriveFieldGroupLayout returns null and there is no untitled bucket to credit. The in-process control, which strips one field at a time, is the one that catches that class (A3).
• EC2 (nightly control), the rule's findings stop carrying the field-no-consumers id. This is plant -ablated, lint rebuilt, preflight present in 4 built files. Result: 4 failed, 11 passed, exactly the 4 control legs. Restore leg: lint rebuilt, marker absent, tree clean.

Verification (at d94a0d6 unless noted)

• pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2, in 3 shards: 82 + 82 + 83 files. One file, published-subpath-console.pin.test.ts, first refused with "packages/cli is not built" (prerequisite, not a red). After pnpm --filter @objectstack/cli build it passed (14/14). All other files passed: 1315 + 1079 + 1095 tests, 14 skipped.
• Integration tier, per-PR file the blank starter feeds: create-objectstack-stack-reach.test.ts passed (4/4).
• Nightly, OS_TEST_TIERS=nightly: starter-field-consumers.e2e.test.ts passed (15/15), and generate-scaffold-gates.e2e.test.ts passed with the empty ledger (37/37).
• pnpm --filter @objectstack/cli typecheck: exit 0. check:test-typecheck holds the ledgered 28 errors in 3 files. tsc -p tsconfig.test.json --listFiles includes all three touched test files, with 0 errors in them. pnpm --filter create-objectstack typecheck and pnpm --filter create-objectstack test (16 files, 249 tests) both exit 0. That suite includes the shipped-comment pins, which resolve the new docs link.
• The gate union from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands: 68 commands, each run at d94a0d6 with its exit code captured before any pipe, all exit 0. --ran reconciliation: "68 derived, 68 run, 0 NOT-MEASURED, 0 UNRUN". On an earlier pass, three of them first answered as follows. check:cross-package-test-inputs was red: the pin's header named the lint rule's repo path in prose, which the gate reads as a read. It was reworded in d94a0d6. check:dual-build-cjs-loads and check:i18n-coverage refused with PREREQUISITE NOT MET (exit 3). After a workspace build both were green, and both are green in the final union.
• Lint is a proven narrowing, not a pnpm lint run. ① The population comes from eslint.config.mjs: pnpm lint is eslint . --no-inline-config, minus the global NEVER_LINTED set (node_modules, dist, build, .next, .turbo), and none of the 5 touched TS files falls in it. ② eslint --no-inline-config --format json on those 5 files reports 5 file results, 0 errors and 0 warnings. No result is a "file ignored" warning. ③ The config never enables type-aware linting (no parserOptions.project, no projectService) and loads no cross-file rule plugin. Its only reads are two baseline JSON files this diff does not touch. So no untouched file's verdict can move.

Acceptance notes

• main moved 7 commits past 69a12a0 while this ran (to 1d0600b). None of them touches init.ts, the create-objectstack templates, generate.ts, generate-scaffold-gates.e2e.test.ts or validate-field-consumers.ts.
• The before readings were one project per waker. The nightly pin uses one project per starter with all three wakers, to keep it at about 25 cold starts. The per-waker split is held per-PR by the in-process pin.
• Measured on the way, not filed (no defect class): os validate on a bare os init -t app project prints one plain-string warning, "No apps or plugins defined — this stack may not do much". It is not a rule finding, and it is the same before and after.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/cli, objectstack-blank, touching 2 documentable anchor(s).

11 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/object-extensions.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/data-modeling/schema-design.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/deployment/cli.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/getting-started/examples.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/getting-started/your-first-project.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/plugins/index.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/protocol/kernel/i18n-standard.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/protocol/kernel/index.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/ui/create-vs-edit-form.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/ui/field-grouping-and-order.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/ui/forms.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))

⛔ 5 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v15.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/releases/v17/17-1.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/releases/v17/17-3.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note))
• content/docs/releases/v17/17-4.mdx (via os init (command, read off packages/cli/src/commands/init.ts))
• content/docs/releases/v17/17-5.mdx (via fieldGroups (symbol, a field of const object $; a field of const object Note), os init (command, read off packages/cli/src/commands/init.ts))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 26 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 4b20c847488c42fc521a64857d32274a8341c306 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 4e4b4b3a1a64f096e2944438286c69197c81bafc — the merge of head d94a0d618c4379bd5fe94d3ff06e40c2760d29fd into base 4b20c847488c42fc521a64857d32274a8341c306, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 4e4b4b3a1a64f096e2944438286c69197c81bafc && git checkout 4e4b4b3a1a64f096e2944438286c69197c81bafc
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 4b20c847488c42fc521a64857d32274a8341c306 d94a0d618c4379bd5fe94d3ff06e40c2760d29fd && git checkout -B drift-repro 4b20c847488c42fc521a64857d32274a8341c306 && git merge --no-ff d94a0d618c4379bd5fe94d3ff06e40c2760d29fd

node scripts/docs-audit/affected-docs.mjs --json 4b20c847488c42fc521a64857d32274a8341c306

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 4b20c847488c42fc521a64857d32274a8341c306 → pass the list as
args.docs, on the commit named under Which tree this was computed on.