feat!: upgrade ObjectStack platform 12/13 → 14.7 (spec 14) (#448)

Bump every @objectstack/* package to ^14.7.0 and specVersion to ^14.0.0;
app version → 2.1.0. Migrate HotCRM metadata off the ObjectStack 14.0
breaking surface (ADR-0090 vocabulary convergence + enable.* flag gates)
and harden seed + opportunity-lifecycle hook for a clean fresh-DB boot.

Breaking-change migrations (driven from docs.objectstack.ai/docs/releases/v14):
- Approval approvers: type 'role' → 'position' on the opportunity-approval
  flow (D3 — 'role' now resolves against the org-membership tier, so the
  sales_manager/sales_director positions routed to nobody and stalled).
- FLS keys object-qualified (spec 14.4): sales_rep/service_agent permission
  sets used bare account.*/opportunity.*/case.* keys that matched nothing;
  requalified to crm_account.*/crm_opportunity.*/crm_case.* so masking applies.

Lint/quality migrations surfaced by spec 14:
- fieldGroups referenced by fields on crm_case/contract/product/quote so the
  grouped record-detail sections actually render.
- crm_campaign_member gets a member_number autonumber + explicit nameField
  (ADR-0079 resolvable record title for the junction object).

Fresh-boot fixes:
- opportunity-lifecycle hook runs the closed-deal freeze-guard BEFORE the
  derived-field recompute, so system writes (post-seed ownership backfill)
  to closed opportunities are no longer rejected — kills 23 boot-time
  BodyRunner errors.
- seed 'completed' task gets completed_date to satisfy completed_date_required.

Docs: AGENTS.md now points platform upgrades at the official release notes
(docs.objectstack.ai/docs/releases) as the required first reference.

Verified: validate + typecheck + build + lint (zero warnings) + test (17/17)
green; browser-verified login → dashboards → lists → record detail with live
seed data, zero boot errors and no post-login console errors.


Claude-Session: https://claude.ai/code/session_01YV2dfQ9eR8NYKLSTVLKavY

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

Author: os-zhuang

AGENTS.md

@@ -167,6 +167,24 @@ Use the most specific `Field` type available from `@objectstack/spec/data`:
 > "fail at install" wording is stale. Don't mass-rename UI/automation items to
 > chase that warning.
 
+## ⬆️ Platform Upgrades (ObjectStack version bumps)
+
+When upgrading the `@objectstack/*` dependency line, **start from the official
+release notes — do not reverse-engineer breaking changes from `node_modules`
+changelogs**:
+
+1. **Read the release notes first**: <https://docs.objectstack.ai/docs/releases>
+   (per-major pages, e.g. `/docs/releases/v14`, carry the breaking-change list
+   and a migration checklist with before/after examples).
+2. Per-package details live in each package's `CHANGELOG.md`
+   (`node_modules/@objectstack/<pkg>/CHANGELOG.md`) — use these to supplement,
+   not replace, the release notes. Breaking changes reference ADRs for rationale.
+3. Bump all `@objectstack/*` packages **together** (they are version-locked),
+   update `specVersion` in `objectstack.manifest.json` to the new major,
+   then run the full verify suite and browser-verify (see below).
+4. Record the upgrade in `CHANGELOG.md` following the existing entry format
+   (what changed on the platform, what metadata was migrated and why).
+
 ## 🚫 Out of Scope (Platform Features)
 
 The following are **NOT** in HotCRM's scope — they are platform-level features provided by `@objectstack/runtime` or other platform packages:

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to HotCRM are documented in this file. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); HotCRM follows [Semantic Versioning](https://semver.org/).
 
+## [2.1.0] — 2026-07-14
+
+Platform upgrade to ObjectStack **14.7** — a major line bump (from 12/13). Manifest `specVersion` now declares `^14.0.0` (was `^12.0.0`); app version `2.1.0`. ObjectStack 14 completes the ADR-0090 permission-model vocabulary convergence and turns the object `enable.*` capability flags into real runtime gates. This release migrates HotCRM's metadata off every 14.0 breaking surface and hardens the seed + opportunity-lifecycle hook so a fresh-DB boot is completely clean. Built, validated, type-checked, linted (zero warnings), unit-tested (17/17), and browser-verified against `@objectstack/* ^14.7.0` (login → HotCRM app → Executive / Sales / Service / CRM Overview dashboards with live seeded data → Accounts / Opportunities / Cases lists → account record detail with grouped field sections; no boot errors, no post-login console errors).
+
+Upgrade migration was driven from the official release notes at <https://docs.objectstack.ai/docs/releases> (per-major page `/docs/releases/v14`), and [`AGENTS.md`](AGENTS.md) now documents that page as the required first reference for any future platform bump.
+
+### Changed
+
+- **ObjectStack platform → 14.7** across all `@objectstack/*` packages (from `12`/`13`).
+- **Approval approvers use `type: 'position'` instead of `type: 'role'` (ADR-0090 D3, spec 14.0).** In 14 the `role` approver type resolves against the better-auth org-membership tier (`sys_member.role`: owner/admin/member) — the CRM's `sales_manager` / `sales_director` are org **positions**, not membership tiers, so under the old spelling the opportunity-approval flow routed to nobody and stalled. Both approval nodes in [`src/flows/opportunity-approval.flow.ts`](src/flows/opportunity-approval.flow.ts) now target the declared positions via `type: 'position'`.
+- **FLS keys are object-qualified (spec 14.4, `security-fls-unqualified-key`).** The runtime evaluator matches field-permission keys by `<object>.<field>` prefix; the bare keys in the `sales_rep` and `service_agent` permission sets (`account.*`, `opportunity.*`, `case.*`) matched nothing and their declared masking never enforced. Requalified to `crm_account.*` / `crm_opportunity.*` / `crm_case.*` so the FLS actually applies.
+- **`fieldGroups` are now referenced by their fields.** Spec 14's lint flagged `crm_case`, `crm_contract`, `crm_product` and `crm_quote` declaring field groups that no field pointed at — the groups never rendered. Every field on those four objects now carries a `group:` assignment, so record detail pages render the intended grouped sections (verified in the browser on the account/case detail layout).
+- **`crm_campaign_member` declares a resolvable record title (ADR-0079).** The junction object had no title-eligible stored field, so records displayed as raw IDs. Added a `member_number` autonumber and pointed `nameField` at it explicitly.
+
+### Fixed
+
+- **Opportunity-lifecycle hook no longer rejects system writes to closed deals.** The `beforeUpdate` freeze-guard ran *after* the derived-field recompute injected `expected_revenue`/`probability` into the input, so the post-seed ownership backfill (and any framework re-stamp) on a closed opportunity was rejected for fields the caller never touched — surfacing as 23 `BodyRunner` errors on every fresh-DB boot. The guard now runs first and judges only the caller's actual field edits; a fresh boot is error-free.
+- **Seed task with `status: 'completed'` now sets `completed_date`.** The "Send welcome package to Stark Medical" seed row tripped the `completed_date_required` validation rule (an `Insert operation failed` on every fresh boot). Added `completed_date` to satisfy the rule.
+
 ## [2.0.0] — 2026-07-07
 
 Platform upgrade to ObjectStack **12.3** — a major line bump. Manifest `specVersion` now declares `^12.0.0` (was `^10.0.0`); app version `2.0.0`. ObjectStack 12 introduces the **metadata-liveness** gate (ADR-0049): the compiler now emits an advisory warning for any authored property that is parsed but has no runtime consumer. This release migrates HotCRM off that dead surface so `pnpm build` / `pnpm dev` compile with **zero warnings**. Built, validated, type-checked, unit-tested (17/17), and browser-verified against `@objectstack/* ^12.3.0` (login → HotCRM app → Executive / Sales / Service / CRM Overview dashboards with live seeded data and the reworked aggregated tables; no console errors).

objectstack.config.ts

@@ -31,7 +31,7 @@ export default defineStack({
   manifest: {
     id: 'app.objectstack.hotcrm',
     namespace: 'crm',
-    version: '2.0.0',
+    version: '2.1.0',
     type: 'app',
     name: 'HotCRM',
     description: 'AI-Native CRM for the ObjectStack marketplace — Accounts, Contacts, Leads, Opportunities, Cases, Knowledge, Forecasts, Campaigns, Contracts.',

objectstack.manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://schemas.objectstack.dev/template-manifest.json",
   "name": "hotcrm",
-  "specVersion": "^12.0.0",
+  "specVersion": "^14.0.0",
   "manifestId": "app.objectstack.hotcrm",
   "displayName": "HotCRM",
   "description": "AI-Native CRM for the ObjectStack marketplace — Accounts, Contacts, Leads, Opportunities, Cases, Knowledge, Forecasts, Campaigns, and Contracts in one production-grade workspace.",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hotcrm",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "HotCRM - Production CRM built on ObjectStack",
   "private": true,
   "main": "./objectstack.config.ts",
@@ -26,17 +26,17 @@
   },
   "packageManager": "pnpm@10.33.0",
   "dependencies": {
-    "@objectstack/account": "^13.0.0",
-    "@objectstack/cli": "^13.0.0",
-    "@objectstack/driver-memory": "^13.0.0",
-    "@objectstack/driver-sql": "^13.0.0",
-    "@objectstack/driver-sqlite-wasm": "^13.0.0",
-    "@objectstack/metadata": "^13.0.0",
-    "@objectstack/objectql": "^13.0.0",
-    "@objectstack/runtime": "^13.0.0",
-    "@objectstack/service-analytics": "^13.0.0",
-    "@objectstack/service-automation": "^13.0.0",
-    "@objectstack/spec": "^13.0.0"
+    "@objectstack/account": "^14.7.0",
+    "@objectstack/cli": "^14.7.0",
+    "@objectstack/driver-memory": "^14.7.0",
+    "@objectstack/driver-sql": "^14.7.0",
+    "@objectstack/driver-sqlite-wasm": "^14.7.0",
+    "@objectstack/metadata": "^14.7.0",
+    "@objectstack/objectql": "^14.7.0",
+    "@objectstack/runtime": "^14.7.0",
+    "@objectstack/service-analytics": "^14.7.0",
+    "@objectstack/service-automation": "^14.7.0",
+    "@objectstack/spec": "^14.7.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.11.1"