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

[objectstack-fleet]

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

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 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 — 137 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 0bbe4005e82fce2058238720cac7ba5cd2f182d5 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c6f6078b870f68fc68211f68d9461ac62e6ed86a — the merge of head de53a276921cb22d9554e78b1f929cafff6b84e6 into base 0bbe4005e82fce2058238720cac7ba5cd2f182d5, 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 c6f6078b870f68fc68211f68d9461ac62e6ed86a && git checkout c6f6078b870f68fc68211f68d9461ac62e6ed86a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0bbe4005e82fce2058238720cac7ba5cd2f182d5 de53a276921cb22d9554e78b1f929cafff6b84e6 && git checkout -B drift-repro 0bbe4005e82fce2058238720cac7ba5cd2f182d5 && git merge --no-ff de53a276921cb22d9554e78b1f929cafff6b84e6

node scripts/docs-audit/affected-docs.mjs --json 0bbe4005e82fce2058238720cac7ba5cd2f182d5

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: de53a276921cb22d9554e78b1f929cafff6b84e6
Local-runs: none

Inputs, and nothing else: card #20494 (body; triage grade 5877534733; claim 5878189120; os-dev-report 5879698506), PR #20521 (body; its one comment, the Docs Drift Check 5879671411; its four-file list; the net diff origin/main...head, merge base 4a1df19656, 21+ / 10-), and the 33 check-runs on the head, read once for this record (at 2026-09-28T22:27Z). Every code reading below is off the head's tree via git objects; no worktree, build, test or gate was run.

① Derived judgments

J1 — the new describe is TRUE of the runtime: RIGHT. packages/plugins/plugin-audit/src/audit-writers.ts at the head: activityType starts as activityTypeFor(action) (:1497; the function at :245 yields only created / updated / deleted); action comes from actionFor (:237), which maps exactly afterInsert / afterUpdate / afterDelete and nothing else. The create (:1498) and delete (:1502) arms assign their summary and never reach the milestone match; matchMilestone is called only in the else arm (:1521), which is action === 'update', and it returns null unless both the before and after rows exist (:656). The override is if (milestone.type) activityType = milestone.type; (:1540) and matchMilestone forwards type only when it is a string (:660). So an unset type leaves updated, and a milestone can fire only on an update — both halves of the new text. Any other path? None: the only runtime consumer of activityMilestones at the head is this file (the other hits are the form, the four generated form-locale bundles, lint's docblock, spec baselines and docs), there is no bulk or upsert arm in actionFor, and no other sys_activity writer reads milestones. One observation, not a defect of the describe: an explicit empty-string type is falsy at :1540 and behaves as unset, which the wording "left unset" covers in practice.

J2 — content/docs/references/data/object.mdx:357 is exactly the generator's output: RIGHT. The nested-shape row is emitted at packages/spec/scripts/lib/schema-section.ts:536-543 as escapeMdxDescription(description + externalVocabularyNote + dimensionlessNote) with newlines folded and backslashes then pipes escaped, then | **key** | type | required-cell | desc |. lib/escape-mdx.ts rewrites only an opening curly brace, an opening angle bracket (less-than sign) and backtick runs; the new describe carries none of those, no pipe, no backslash and no newline; the two note helpers key on externalVocabulary / dimensionless meta the prop does not carry (:289, :325); the type cell stays string and the required cell optional. The cell is therefore the describe text byte-for-byte, which is what the diff's mdx line holds. The two lines are the only two occurrences of the wording in the head tree. CI's own reading of this is check:docs in Type Check · source gates — success on this head.

J3 — the plugin-audit test edit landed on the right file and changed only title and docblock: RIGHT. The claim named audit-milestone-summary.test.ts; that file holds no "filed separately" docblock and no default pin — its milestone at :159 sets type: 'completed' explicitly and :401 asserts that explicit value. The pin the card body itself cited is activity-type-vocabulary-enforcement.test.ts :268-:283, and that is the file the dev edited. The full-file diff against origin/main is one hunk; the changed lines are the seven-line docblock (now five lines) and the it( title; every assertion line — boot(), the t3 insert, moveStage(engine, 't3', 'plain'), expect(activityTypes(storeFor)).toEqual(['created', 'updated']) — is diff context, i.e. byte-identical. The dev stopped on the breach of the claim's file list and explained it in the report, as the claim required.

J4 — no other author-shown copy still states completed as the default: RIGHT. Head-tree grep for the old wording finds only the two changed surfaces. Every remaining default ... completed hit is the flow end node's outcome, a real default in a different schema. The object form's milestone row (packages/spec/src/data/object.form.ts:496) reads "Unset: updated." and its four generated locale copies (en, es-ES, ja-JP, zh-CN metadata-forms.generated.ts) say the same; sys-activity.object.ts and feed.zod.ts describe the channel without naming a default; skills/** has no mention; packages/spec/json-schema/ is untracked (only the name manifest json-schema.manifest/ is tracked, and it lists schema names, not text), so the served JSON Schema is rebuilt from the describe.

J5 — accept set and public surface: unchanged, and the diff claims nothing more: RIGHT. The Zod shape stays z.string().optional(); no authorable key is added or removed, so the untouched authorable-surface shards are correct; no export changes, so the untouched api-surface shards are correct; no ADR-0087 entry is owed. The Docs Drift Check comment listed nothing and says so is not a clean bill; the hand re-read it prescribes is J4.

J6 — gate coverage (the dev ran about 10 of 112 derived families locally; the rest were left to CI). Check-run conclusions on this head, read once: 33 runs, 0 failed, 2 skipped, 9 not concluded. Where the derived families land:

• Type Check · source gates — SUCCESS: check:docs, check:authorable-surface, check:export-origins, check:skill-docs, check:skill-refs, check:spec-changes, check:upgrade-guide, check:react-blocks, check:type-check-coverage, and check:generated --reconcile-only.
• Type Check · debt ledger — SUCCESS: check:type-check-debt.
• Check Changeset — SUCCESS: check-empty-changeset, check-adr-0087-registration, check-changeset-no-major, all --base the merge base.
• Spec property liveness — SUCCESS: check:liveness, check:strictness-ledger, check:empty-state, check:variant-docs.
• Build Core, Build Docs, Dogfood Regression Gate (aggregate, three shards and Verify CLI), Governed Surface Queue Guard (no governed path in the file list), and the four claim / closing-target guards — SUCCESS.
• Test Core (2/6) — SUCCESS. Test Core (1/6), (3/6), (4/6), (5/6), (6/6) — NOT CONCLUDED (in progress); the shards carry each package's test via turbo, so @objectstack/spec and @objectstack/plugin-audit — the suites the dev ran locally, including the renamed pin — sit on shards not yet concluded. The required aggregate Test Core does not exist on this head yet.
• Lint & Repo Gates — NOT CONCLUDED: this is where check:doc-authoring (the dispatch-named gate), check:nul-bytes, check:issue-citations, check:engine-double-contract, check:cross-package-test-inputs, check:test-source-alias, check:migration-registry, pnpm lint and the rest of the root check:* roster run.
• Type Check · consumer gates — NOT CONCLUDED: check:api-surface, check:exported-any, check:dual-source-exports, check:skill-examples, check:i18n, check:i18n-coverage, check:i18n-walk-parity.
• Type Check · workspace — NOT CONCLUDED: turbo run typecheck, which is the spec and plugin-audit typecheck scripts (spec's chains check:scripts-typecheck and check:test-typecheck). The required aggregate TypeScript Type Check does not exist on this head yet.
• Temporal Conformance (live PG + MySQL) — NOT CONCLUDED.
• Console Pin Gate and Packed-tarball smoke (opt-in) — SKIPPED, both by design (no console pin touched; opt-in). Validate Package Dependencies is absent because its path filter (package.json, lockfile, workspace files) matches nothing here.
• Derived family with no CI answer at all: check:declaration-map — a check:generated ledger row that no workflow step invokes (it is run only by the local sweep and by scripts/regen-artifacts.mjs). Its artifact maps TS declaration names to registry names and carries no describe text, so this diff cannot stale it; the dev's local 15-gate check:generated sweep, green, is the only reading of it. A standing repo fact, not this diff's, noted for the seat.
  No concluded run failed, so there is no failure to attribute. The nine unconcluded runs and the two absent aggregates are named here, not presumed green: this record does not vouch for them, and the enqueue precondition (every check green) is not met at this read.

② Semver level

The diff publishes from @objectstack/spec: a .describe() string ships in dist, in the served JSON Schema and in the generated reference page. .changeset/20494-milestone-type-default-describe.md declares '@objectstack/spec': patch — the right level for a corrected description with no shape change (never skip-changeset, which is for a diff that publishes nothing). The PR body's Clause-② declaration reads no, the changeset carries the same line, and the diff neither widens nor narrows any accept set (J5), so no with no arm is the correct declaration; Check Changeset concluded success on it. The changeset body states what shipped and why without a migration, which is right because nothing an author can write changed.

③ Boundary flags

• Dev flag (report): the claim's file list named audit-milestone-summary.test.ts; the dev edited activity-type-vocabulary-enforcement.test.ts instead. ANSWERED — verified in J3; the dev's reading is correct and the claim's was the slip.
• Dev flag (report): 102 of 112 derived families unrun locally, deferred to CI. ANSWERED — mapped in J6; the families with a concluded CI answer are green; the rest are named as unconcluded, with one family (check:declaration-map) that has no CI step at all and cannot be staled by this diff.
• Dev flag (report): os-verify-lock.sh timeouts (exit 99) during heavy contention were treated as NOT MEASURED and every gate was re-run to a real verdict. ANSWERED — nothing in the record depends on those local readings; the check-runs are the verdict.
• Claim note: same-file concurrency with packages/spec/src: 1,277 comment lines still cite 170 deleted tracker numbers (1,295 sites) — the staged remainder of ruling C+D on #19123, measured by PR #20226 #20234 stage 3 on object.zod.ts comment lines. ANSWERED — the PR is mergeable at this read; the later lander merges, and content/docs/references/** goes through the regen merge script as the claim says.
• Docs Drift Check "checkout carried uncommitted changes" warning. ANSWERED — a property of that CI checkout, not of this diff; the hand re-read the check prescribes is J4.
• open_questions: none filed by the dev. out_of_scope_findings: none. This review adds none that need escalation; the empty-string observation in J1 and the check:declaration-map note in J6 are observations for the seat, not defects.

Implemented-by: claude/issue-20494-milestone-type-default-describe
Reviewed-by: session_014EJ1ED8X4MMrT18BhVx4tx

VERDICT: PASS

---

Generated by Claude Code