fix(spec): activityMilestones[].type describe states the real default (#20494) (#20521)

Fixes #20494

Clause-②: no

## What changed

- `packages/spec/src/data/object.zod.ts` (~:2123): rewrote the
`activityMilestones[].type` `.describe()` to state the real default — an
unset `type` keeps the update row's kind, `updated`. No schema shape
change.
- Regenerated `content/docs/references/data/object.mdx` with `gen:docs`
(never hand-edited).
-
`packages/plugins/plugin-audit/src/activity-type-vocabulary-enforcement.test.ts`:
corrected the pin's title and docblock only — they stop describing a
divergence and stop saying it was "filed separately" (this card is where
it was filed). Its assertions are byte-for-byte unchanged.
- `.changeset/20494-milestone-type-default-describe.md`
(`@objectstack/spec` patch, `Clause-②: no`).

## Why

`audit-writers.ts` starts `activityType` from `activityTypeFor(action)`,
and a milestone can only fire on the UPDATE branch (`create` / `delete`
return their own summary before the milestone match runs), so an unset
`type` has always emitted `updated`, never `completed`. `milestone.type`
overrides it only when the author actually sets it — that half of the
old describe was correct and is unchanged. The plugin-audit pin
(`activity-type-vocabulary-enforcement.test.ts`) already measured this
real answer; only its title and docblock claimed a divergence and said
the finding was filed separately.

## Dedupe search for other stale copies

A repo-wide grep for the old wording, and for every `activityMilestones`
mention, found no other hand-written copy of the "completed" default.
`object.form.ts`'s `activityMilestones.type` help text (shipped with PR
#20485 — "Unset: updated.") already states the real default and is
unchanged.

## Verification record

Commands run in this worktree, foreground, through
`scripts/pm/os-verify-lock.sh` where heavy:

- `pnpm --filter @objectstack/spec build` — pass.
- `pnpm --filter @objectstack/spec run check:generated` — all 15
generated artifacts green after `pnpm --filter @objectstack/spec run
gen:docs` (only `check:docs` was stale, for exactly this describe
change).
- `pnpm --filter @objectstack/spec test` — 572 test files / 16796 tests
passed, 1 todo.
- `pnpm --filter @objectstack/spec typecheck` — pass.
- `pnpm --filter '@objectstack/plugin-audit^...' build` (dependency
closure) — pass.
- `pnpm --filter @objectstack/plugin-audit test` — 25 test files / 363
tests passed, including the renamed pin.
- `pnpm --filter @objectstack/plugin-audit typecheck` — pass.
- `pnpm check:doc-authoring` (dispatch-named — no tracker number in the
describe) — pass.
- `node scripts/check-nul-bytes.mjs` — pass.
- `node scripts/check-adr-0087-registration.mjs`,
`check-changeset-no-major.mjs`, `check-empty-changeset.mjs`,
`check-issue-citations.mjs` (`--self-test` and `--base origin/main`,
matched by the new changeset file) — all pass.

`node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
--ran <record>` reconciliation: 112 families derived from this diff's
paths, 102 UNRUN locally. Those are whole-tree/whole-package scans this
describe-text-only change (no export, no authorable key, no schema shape
change) does not plausibly touch — `check:generated`'s own 15-gate sweep
already covers the ones that read the schema/docs pipeline this change
lands in (`check:docs`, `check:api-surface`, `check:authorable-surface`,
`check:export-origins`, `check:declaration-map`,
`check:strictness-ledger`, `check:liveness`, `check:test-typecheck`).
The remaining UNRUN families are deferred to CI's farm per this repo's
local-verification scope.

## Acceptance notes

Nothing found outside this card's file surface.

---
_Generated by [Claude
Code](https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/20494-milestone-type-default-describe.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': patch
+---
+
+`activityMilestones[].type`'s `.describe()` now states the real default: an unset `type` keeps the update row's kind, `updated` (#20494)
+
+Clause-②: no
+
+No behaviour changes and no schema shape change. `object.zod.ts`'s `activityMilestones[].type` field described its default as `"completed"`; the runtime never wrote that. `audit-writers.ts` starts `activityType` from `activityTypeFor(action)`, and a milestone can only fire on the UPDATE branch (`create` / `delete` return their own summary before the milestone match ever runs), so an unset `type` has always emitted `updated`. `milestone.type` overrides it only when the author actually sets it — that half of the describe was correct and is unchanged.
+
+The corrected string is the published half: it ships in `packages/spec/dist/*.d.ts`, in the JSON Schema under `packages/spec/json-schema/`, and in the generated `content/docs/references/data/object.mdx` (regenerated with `gen:docs`, never hand-edited). A repo-wide search for the old wording found no other hand-written copy; `object.form.ts`'s `activityMilestones.type` help text ("Unset: updated.", shipped with PR #20485) already stated the real default and is unchanged.
+
+`packages/plugins/plugin-audit/src/activity-type-vocabulary-enforcement.test.ts` already measured the runtime's real answer — its title and docblock are corrected in the same PR to stop describing a divergence and stop saying the finding was "filed separately" (this card, #20494, is where it was filed). Its assertions are byte-for-byte unchanged.

content/docs/references/data/object.mdx

@@ -354,7 +354,7 @@ const result = ApiMethod.parse(data);
 | **field** | `string` | ✅ | Field to watch (typically a status/stage select). |
 | **value** | `string` | ✅ | The value the field must transition INTO to fire the milestone. |
 | **summary** | `string` | ✅ | Activity summary template; `{field}` tokens interpolate the record value. e.g. "Deal won: `{name}`". |
-| **type** | `string` | optional | Activity type for the emitted row (default "completed"). |
+| **type** | `string` | optional | Activity type for the emitted row — left unset, it keeps the update row's kind, "updated" (a milestone only fires on an update). |
 
 ### Nested Shape: `Object.listViews[string]`
 

packages/plugins/plugin-audit/src/activity-type-vocabulary-enforcement.test.ts

@@ -266,15 +266,13 @@ describe('[#8203] sys_activity.type — the writers emit declared values', () =>
   });
 
   /**
-   * The real default when a milestone omits `type`. Pinned because the spec's
-   * own field description says otherwise — `object.zod.ts` documents
-   * `activityMilestones[].type` as 'Activity type for the emitted row (default
-   * "completed")', while the code default is `activityTypeFor(action)` and a
-   * milestone can only fire on the UPDATE branch, making it `updated`.
-   * Filed separately; pinned here so the divergence is measured rather than
-   * argued from either side's prose.
+   * The real default when a milestone omits `type`: `activityTypeFor(action)`,
+   * and a milestone can only fire on the UPDATE branch, so the emitted row is
+   * `updated`. `object.zod.ts`'s `activityMilestones[].type` describe states
+   * this default (#20494); pinned here so the runtime behaviour stays
+   * measured, not just described.
    */
-  it('a milestone without `type` emits `updated` — not the "completed" the spec text claims', async () => {
+  it('a milestone without `type` keeps the update row\'s kind, `updated`', async () => {
     const { engine, storeFor } = await boot();
     await engine.insert('biz_ticket', { id: 't3', title: 'Three', stage: 'open' });
     await moveStage(engine, 't3', 'plain');

packages/spec/src/data/object.zod.ts

@@ -2120,7 +2120,7 @@ const ObjectSchemaBase = strictObject(
     field: z.string().describe('Field to watch (typically a status/stage select).').meta({ title: 'Field' }),
     value: z.string().describe('The value the field must transition INTO to fire the milestone.').meta({ title: 'Value' }),
     summary: z.string().describe('Activity summary template; {field} tokens interpolate the record value. e.g. "Deal won: {name}".').meta({ title: 'Summary' }),
-    type: z.string().optional().describe('Activity type for the emitted row (default "completed").').meta({ title: 'Type' }),
+    type: z.string().optional().describe('Activity type for the emitted row — left unset, it keeps the update row\'s kind, "updated" (a milestone only fires on an update).').meta({ title: 'Type' }),
   })).optional().describe('Declarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2).'),
 
   // ADR-0020: record state machines are not a separate `stateMachines` map —