Merge pull request #1791 from objectstack-ai/claude/adr-prioritization-review-11ul9m

os-zhuang · web-flow · commit fa024d7d0892 · 2026-06-12T20:42:13.000+05:00
docs(adr): prioritization review — status calibration + ranked next steps
diff --git a/docs/adr/0007-settings-manifest-and-kv-store.md b/docs/adr/0007-settings-manifest-and-kv-store.md
@@ -1,6 +1,6 @@
 # ADR-0007: Settings — Manifest + K/V Store + Resolver (Apple-style)
 
-**Status**: Draft (2026-05-20)
+**Status**: Accepted — backend implemented; UI pending (objectui) (proposed 2026-05-20 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (Metadata Customization Overlay), [ADR-0006](./0006-project-environment-split.md) (Project/Environment Split)
 **Consumers**: `@objectstack/spec`, `@objectstack/platform-objects`, new `@objectstack/service-settings`, `@objectstack/plugin-auth` (Setup app), `objectui` (Settings renderer)
diff --git a/docs/adr/0015-external-datasource-federation.md b/docs/adr/0015-external-datasource-federation.md
@@ -1,6 +1,6 @@
 # ADR-0015: External Datasource Federation
 
-**Status**: Proposed (2026-05-29)
+**Status**: Accepted — backend/REST/CLI implemented; Studio UI + extra dialect drivers pending (proposed 2026-05-29 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (one Zod source of truth per metadata type)
 **Consumers**: `@objectstack/spec`, `@objectstack/runtime`, `@objectstack/objectql`, `@objectstack/plugins/driver-sql`, `@objectstack/services/service-ai`, `@objectstack/cli`, `../objectui`
diff --git a/docs/adr/0023-openapi-to-connector-generator.md b/docs/adr/0023-openapi-to-connector-generator.md
@@ -1,6 +1,6 @@
 # ADR-0023: OpenAPI → Connector Generator — Bulk Connectors From Declarative API Specs
 
-**Status**: Proposed (2026-06-01)
+**Status**: Accepted — library implemented; CLI + examples pending (proposed 2026-06-01 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0015](./0015-external-datasource-federation.md) (open mechanism / enterprise lifecycle split), [ADR-0018](./0018-unified-node-action-registry.md) (`connector_action` baseline dispatch + `engine.registerConnector()`), [ADR-0022](./0022-connectors-vs-messaging-channels.md) (Connector = transport/integration mechanism; not the messaging-semantic layer)
 **Consumers**: `@objectstack/spec` (`integration/connector.zod.ts`), `@objectstack/service-automation` (connector registry on the engine), `@objectstack/runtime` (the `GET /api/v1/automation/connectors` discovery route), new `@objectstack/connector-openapi`, the Studio flow palette
diff --git a/docs/adr/0024-mcp-connectors.md b/docs/adr/0024-mcp-connectors.md
@@ -1,6 +1,6 @@
 # ADR-0024: MCP Servers as Connectors — Adopting an Open, Vendor-Neutral Tool Protocol
 
-**Status**: Proposed (2026-06-01)
+**Status**: Accepted — library implemented; examples pending (proposed 2026-06-01 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0011](./0011-actions-as-ai-tools.md) (actions as AI tools), [ADR-0015](./0015-external-datasource-federation.md) (open mechanism / enterprise lifecycle split), [ADR-0018](./0018-unified-node-action-registry.md) (`connector_action` baseline dispatch + connector registry), [ADR-0022](./0022-connectors-vs-messaging-channels.md) (Connector = transport/integration mechanism), [ADR-0023](./0023-openapi-to-connector-generator.md) (OpenAPI → Connector generator)
 **Consumers**: `@objectstack/spec` (`integration/connector.zod.ts`), `@objectstack/service-automation` (connector registry on the engine), `@objectstack/runtime` (the `GET /api/v1/automation/connectors` discovery route), new `@objectstack/connector-mcp`, `@objectstack/service-ai` (the same MCP tools double as AI tools, ADR-0011), the Studio flow palette
diff --git a/docs/adr/0029-kernel-object-ownership-and-platform-objects-decomposition.md b/docs/adr/0029-kernel-object-ownership-and-platform-objects-decomposition.md
@@ -1,6 +1,6 @@
 # ADR-0029: Kernel Object Ownership — First-Party Capabilities as Plugins That Own Their Data, and Decomposing the `platform-objects` Monolith
 
-**Status**: Proposed (2026-06-01)
+**Status**: Accepted — K0/K1/K2/D7 implemented; K3 (pending ADR-0030/storage) + K4 cleanup remaining (proposed 2026-06-01 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md) (package as first-class citizen), [ADR-0019](./0019-app-as-consumer-unit.md) (app as the consumer-facing unit), [ADR-0025](./0025-plugin-package-distribution.md) (plugin package distribution + dependencies)
 **Related**: [ADR-0028](./0028-metadata-naming-and-namespace-isolation.md) (metadata naming & namespace isolation) **depends on** this ADR — its D5/D6 (reserved `sys` namespace, single-owner-per-object, apps-cannot-define-kernel) assume the kernel is properly owned. This ADR is sequenced **first** and is independently valuable; ADR-0028 owns the naming model, this ADR owns kernel object *ownership*.
diff --git a/docs/adr/0032-unified-expression-layer.md b/docs/adr/0032-unified-expression-layer.md
@@ -1,6 +1,6 @@
 # ADR-0032: Expression layer for an AI-authored platform — validate-by-default, schema-aware, one CEL language, no silent failure
 
-**Status**: Proposed (2026-06-02)
+**Status**: Accepted — implemented; designer builders pending (objectui) (proposed 2026-06-02 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0010](./0010-nl-to-flow-authoring.md) + [ADR-0011](./0011-actions-as-ai-tools.md) (AI authoring of metadata — **the design center**), [ADR-0018](./0018-unified-node-action-registry.md) (open action registry), [ADR-0031](./0031-advanced-flow-node-executors-and-dag.md) (structured, statically-analyzable constructs for AI)
 **Consumers**: `@objectstack/formula` (CEL engine + stdlib + template interpolation + validator), `@objectstack/spec` (expression-field types + introspection: every `condition`/`guard`/`value`/template field across data / automation / ui / security; the coercion in `shared/expression.zod.ts`), `@objectstack/services/service-automation` (`engine.ts` `evaluateCondition`, `builtin/template.ts`, builtin node executors), `@objectstack/cli` (compile-time validation in `objectstack build`), the **agent tool layer** (an `validate_expression` / schema-introspection tool surfaced to authoring agents), `../objectui` (flow designer condition/template builders)
diff --git a/docs/adr/0034-transactional-writes-and-ambient-transaction.md b/docs/adr/0034-transactional-writes-and-ambient-transaction.md
@@ -1,6 +1,6 @@
 # ADR-0034: Robust multi-write transactions (ambient transaction context)
 
-**Status**: Proposed
+**Status**: Accepted — implemented (v8.0.0) (calibrated 2026-06-12)
 **Author**: surfaced while implementing the cross-object atomic batch (issue #1604) + autonumber sequence (issue #1603)
 **Affects**: `@objectstack/objectql` (engine), `@objectstack/driver-sql` (and every driver), `@objectstack/rest`
 
diff --git a/docs/adr/0036-app-as-rest-api-and-mcp-server.md b/docs/adr/0036-app-as-rest-api-and-mcp-server.md
@@ -1,6 +1,6 @@
 # ADR-0036: Every app is a REST API + an MCP server — make it visible and connectable after build
 
-**Status**: Proposed (2026-06-06)
+**Status**: Accepted — framework implemented; cloud surfacing pending (proposed 2026-06-06 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0011](./0011-actions-as-ai-tools.md) (actions/objects as AI tools), [ADR-0024](./0024-mcp-connectors.md) (MCP as connectors — the *inbound* sibling: ObjectStack **consuming** external MCP servers; this ADR is the *outbound* direction), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (AI builds the metadata; publishing makes it live)
 **Consumers**: `@objectstack/rest` (REST CRUD + `/api/v1/discovery`), new HTTP transport in `@objectstack/mcp`, `@objectstack/platform-objects` (`sys_api_key`), `../objectui` (Developer Hub → new Integrations page; publish surface), `../cloud` (per-env public hostname = the API/MCP base)
diff --git a/docs/adr/0039-token-scope-tree-execution.md b/docs/adr/0039-token-scope-tree-execution.md
@@ -1,6 +1,6 @@
 # ADR-0039: Concurrent durable pause — multi-instance nodes now, token/scope-tree later
 
-**Status**: Proposed (2026-06-11) — revised after a code + industry self-review
+**Status**: Accepted — Track A implemented; Track B deferred (proposed 2026-06-11, revised after a code + industry self-review · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0019](./0019-approval-as-flow-node.md) (durable-pause node via suspend/resume — *between*-flow chaining added in its 2026-06-10 addendum), [ADR-0031](./0031-advanced-flow-node-executors-and-dag.md) (structured `loop` / `parallel` / `try_catch` constructs, DAG invariant), [ADR-0018](./0018-unified-node-action-registry.md) (open node/executor registry)
 **Consumers**: `@objectstack/services/service-automation` (engine core — `executeNode` / `traverseNext` / `runRegion` / `resume`, `SuspendedRun`, `sys_automation_run`), `@objectstack/spec` (`automation/execution.zod.ts`), `../objectui` (Runs panel, flow runner)
diff --git a/docs/adr/0041-flow-trigger-family.md b/docs/adr/0041-flow-trigger-family.md
@@ -1,6 +1,6 @@
 # ADR-0041: Flow trigger family — taxonomy, naming, and the open-source core set
 
-**Status**: Proposed (2026-06-12)
+**Status**: Accepted — Tier 1 implemented (rename deprecation stubs pending) (proposed 2026-06-12 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0018](./0018-unified-node-action-registry.md) (open node/executor registry — descriptors as the engine-owned contract surface), [ADR-0030](./0030-notification-platform-convergence.md) (outbox-backed delivery), [ADR-0012](./0012-notification-platform.md) (notification platform / messaging)
 **Consumers**: `@objectstack/service-automation` (the `FlowTrigger` seam), `@objectstack/cli` (`serve` auto-wiring), runtime presets, Studio flow designer (trigger pickers), future marketplace packaging
diff --git a/docs/adr/0042-approval-sla-escalation.md b/docs/adr/0042-approval-sla-escalation.md
@@ -1,6 +1,6 @@
 # ADR-0042: Approval SLA escalation — a jobs-backed scanner with audit-row idempotency
 
-**Status**: Proposed (2026-06-12)
+**Status**: Accepted — implemented (proposed 2026-06-12 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0019](./0019-approval-as-flow-node.md) (approval as flow node), [ADR-0041](./0041-flow-trigger-family.md) (triggers vs jobs vs hooks — this is the canonical "jobs, not trigger" case), thread interactions (#1740)
 **Closes**: [#1742](https://github.com/objectstack-ai/framework/issues/1742)
diff --git a/docs/adr/0043-actionable-approval-links.md b/docs/adr/0043-actionable-approval-links.md
@@ -1,6 +1,6 @@
 # ADR-0043: Actionable approval links — single-use tokens with a session-less confirm page
 
-**Status**: Proposed (2026-06-12)
+**Status**: Accepted — implemented (proposed 2026-06-12 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0042](./0042-approval-sla-escalation.md) (reserved system actors, audit-first discipline), thread interactions (#1740), [ADR-0012/0030](./0030-notification-platform-convergence.md) (messaging + outbox)
 **Closes**: [#1743](https://github.com/objectstack-ai/framework/issues/1743)
diff --git a/docs/adr/0044-approval-send-back-for-revision.md b/docs/adr/0044-approval-send-back-for-revision.md
@@ -1,6 +1,6 @@
 # ADR-0044: Flow-level send-back-for-revision — `revise` branch + typed back-edge re-entry
 
-**Status**: Proposed (2026-06-12)
+**Status**: Accepted — engine + model implemented; designer pending (objectui) (proposed 2026-06-12 · calibrated 2026-06-12)
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0019](./0019-approval-as-flow-node.md) (approval as a durable-pause flow node), [ADR-0039](./0039-token-scope-tree-execution.md) (single-program-counter suspend model), thread interactions (#1740), [ADR-0042](./0042-approval-sla-escalation.md) (audit-first discipline)
 **Closes**: [#1744](https://github.com/objectstack-ai/framework/issues/1744)
diff --git a/docs/adr/PRIORITIZATION.md b/docs/adr/PRIORITIZATION.md
@@ -0,0 +1,134 @@
+# ADR Prioritization Review
+
+> **Date:** 2026-06-12
+> **Scope:** All 49 ADRs in `docs/adr/`, cross-checked against actual code on `main`.
+> **Method:** Every unfinished ADR was read in full and its `Status:` header was
+> verified against the shipped code (git log + source grep), not taken at face
+> value. This document records the calibrated status and a ranked next-step plan.
+
+---
+
+## 0. Headline finding — the `Status:` headers are systematically stale
+
+The single most important result of this sweep: a large fraction of ADRs marked
+**Proposed** or **Draft** are in fact **substantially or fully shipped** on the
+framework (backend) side. What remains for most of them is the **ObjectUI**
+surface (sibling `../objectui` repo) or **cloud** control-plane work — neither of
+which is owned by this repo.
+
+Consequence: prioritizing off the headers alone overstates the remaining
+framework workload and hides where the real gaps are. The headers should be
+refreshed (see §4).
+
+---
+
+## 1. Status calibration — header vs. real (framework side)
+
+| ADR | Header | Real framework status | Remaining (and where) |
+|---|---|---|---|
+| 0034 transactional writes | Proposed | **Shipped** (v8.0.0 — ambient `AsyncLocalStorage` tx, batch `$ref`) | UI wiring (objectui) |
+| 0032 unified expression layer | Proposed | **Shipped** (CEL, no silent-swallow, build-time validate) | designer builders (objectui) |
+| 0039 concurrent durable pause | Proposed | Track A **shipped** (incl. A2 `map` node) | Track B deferred by design |
+| 0042 approval SLA escalation | Proposed | **Shipped** (jobs-backed scanner, `system:sla`) | — |
+| 0043 actionable approval links | Proposed | **Shipped** (single-use tokens, GET-confirm/POST-exec) | v1 non-goals only |
+| 0044 approval send-back | Proposed | **Shipped** (`returned` status, typed back-edges) | designer (objectui) |
+| 0041 flow trigger family | Proposed | **Shipped** (trigger-api HMAC + queue) | rename deprecation stubs (S) |
+| 0015 datasource federation | Proposed | **Shipped** (3 gates + REST + CLI) | Studio UI, extra drivers |
+| 0023 OpenAPI→connector | Proposed | **Shipped** (library) | CLI, examples |
+| 0024 MCP connectors | Proposed | **Shipped** (library) | examples |
+| 0036 app = REST + MCP | Proposed | **Shipped** framework (api-key, `/api/v1/mcp`) | cloud Integrations page |
+| 0007 settings | Draft | **Shipped** backend (sys_setting, resolver, 7 manifests) | entire UI (objectui) |
+| 0033 AI authoring | Accepted | A–C **shipped** | Phase D = enterprise/cloud |
+| 0019 app = consumer unit | Proposed | **Shipped** (schema-enforced) | Console fills field |
+| 0029 kernel object ownership | Proposed | **Substantially shipped** (K0/K1/K2/D7) | K3 (waits on 0030/storage) + K4 cleanup |
+
+> Note on 0029: `sys` being a **shared** namespace with single-owner-per-object
+> enforcement (not a reserved namespace) is the **intended** K0 design, not a gap.
+
+---
+
+## 2. Genuinely unbuilt framework gaps (the real candidate work)
+
+| ADR | What | Real status | Effort | Value |
+|---|---|---|---|---|
+| **0025 install side** | plugin package install / registry / consent | build/sign/publish shipped; **install half missing** | L | high |
+| **0027 authoring lifecycle** | openDraft→stage→diff→publish(seal)→promote→rollback orchestrator | package absent; only contract stubs | L | high |
+| **0013 bidirectional messaging** | Slack inbound receiver / sessions / multi-account | **~zero code** (messaging is outbound-only) | L | high |
+| **0010-nl-to-flow** | natural language → runnable Flow | **not started** (substrate ready) | L | high |
+| **0028 namespace isolation** | `(namespace,type,name)` identity + physical-name derivation | **still the old prefix model** | L | med |
+| **0026 client-UI plugin dist** | `runtime:'ui'` variant + iframe sandbox | unbuilt, **blocked on 0025** | L | med |
+| 0046 package docs as metadata | `src/docs` → `manifest.docs` | unbuilt, but P0/P1 cheap | S–M | med |
+| 0010 protection L4 / unlock | `frozenPaths` evaluator + unlock RBAC | L3 + audit shipped; **no escape hatch** | M | med |
+| 0017 view Phase 5 | view RLS backend + designer | RLS still **client-enforced**; designer in objectui | S (backend) | med |
+| 0040 unified assistant | tool-scoping enforcement + blueprint scale gate | still advisory; scale gate **not implemented** | M | med-high |
+| 0029 K4 | remove migration-era empty barrels | cleanup only | S | low-med |
+
+---
+
+## 3. Recommended next-step priority
+
+### P0 — GA blockers (not ADRs, but they gate launch)
+From `docs/launch-readiness.md`: **P0-5** (realtime/feed are in-memory only, no
+cluster coordination) and **P1-2** (execution logs / job runs / event log grow
+unbounded). Decide single-instance vs HA and land retention/coordination
+**before** any new feature ADR. These outrank everything below for GA.
+
+### P1 — Complete the distribution loop: `0025 install` + `0027 lifecycle`
+Recent momentum is almost entirely in distribution (package-install command,
+local-manifest-source, marketplace-nav, cloud-connection). The build/publish half
+already shipped; the install / registry / promotion half is the natural join, and
+it is the keystone that unblocks **0026** and subsumes **0016**'s deferred cloud
+publish. Highest value-to-effort coherent line.
+
+### P1.5 — Distribution safety prerequisites
+- **0029 K4** finish (small): drop the empty re-export barrels so the
+  plugin-owned architecture is clean before third-party packages arrive.
+- **0028 namespace isolation** (large): its hard prerequisite (0029) is now
+  largely satisfied, so it is **no longer blocked**. Needed before opening up
+  multi-package third-party co-install, otherwise silent table-name collisions.
+
+### P2 — Outward differentiator: `0013 Slack bidirectional messaging`
+The only one of the five integration ADRs with essentially zero code, and the
+only outward-facing headline gap ("operate ObjectStack from Slack"). ADR-0022
+already routes the human-notification story into it. Promote to P1 if
+conversational Slack is a near-term product goal.
+
+### P3 — Cheap, high-leverage fill-ins (interleave)
+- **0046 package docs** (S) — directly feeds AI grounding.
+- **0010 L4 + unlock escape hatch** (M) — without it a lock can never be lifted.
+- **0017 view RLS backend** + **0040 tool-scoping enforcement** — both are
+  security-shaped (today: client-enforced / advisory); worth elevating near GA.
+
+### P4 — Explicitly deferred
+0039 Track B (token-tree rewrite, demand-gated), 0031 BPMN XML plugin, 0026
+(waits on 0025), 0010-nl-to-flow (high "wow" but pure net-new — after the
+distribution loop).
+
+---
+
+## 4. Status-header corrections to apply
+
+These ADR headers should be updated to reflect shipped reality (framework side).
+Listed here rather than edited in place, since changing an ADR's recorded status
+is a governance act best ratified deliberately.
+
+| ADR | Current header | Suggested |
+|---|---|---|
+| 0007 | Draft | Accepted — backend implemented; UI pending (objectui) |
+| 0032 | Proposed | Accepted — implemented (designer pending, objectui) |
+| 0034 | Proposed | Accepted — implemented (v8.0.0) |
+| 0041 | Proposed | Accepted — Tier 1 implemented |
+| 0042 | Proposed | Accepted — implemented |
+| 0043 | Proposed | Accepted — implemented |
+| 0044 | Proposed | Accepted — engine + model implemented (designer pending) |
+| 0015 | Proposed | Accepted — backend/REST/CLI implemented (UI + drivers pending) |
+| 0023 | Proposed | Accepted — library implemented (CLI/examples pending) |
+| 0024 | Proposed | Accepted — library implemented (examples pending) |
+| 0036 | Proposed | Accepted — framework implemented (cloud surfacing pending) |
+| 0039 | Proposed | Accepted — Track A implemented; Track B deferred |
+| 0029 | Proposed | Accepted — K0/K1/K2/D7 implemented; K3/K4 remaining |
+
+---
+
+_Generated from a five-cluster ADR sweep; file/commit evidence captured in the
+review session. Treat this as a planning input, not a frozen contract._
