Merge remote-tracking branch 'origin/main' into claude/issue-4570-docs-import-surface

# Conflicts:
#	content/docs/references/api/connector.mdx
#	content/docs/references/api/rest-server.mdx

Author: claude

.changeset/adr-anchors-guard.md

@@ -0,0 +1,6 @@
+---
+---
+
+Tooling-only: `pnpm check:adr-anchors` — code an accepted ADR governs must keep naming it (#3723 follow-up). Adds `scripts/check-adr-anchors.mjs` + `scripts/adr-anchors.json` (8 seeded anchors, all in the blast radius of the incident), a `Lint & Type Check` step, and Prime Directive #13 in `AGENTS.md` ("an accepted ADR binds until a superseding ADR says otherwise"). Releases nothing — no package changes.
+
+The incident this closes: three accepted ADRs said `sys_member.role` must never carry RBAC authority, and a patch-level changeset made app-declared names storable there anyway; a follow-up then made it automatic in every host. The mechanism was not carelessness — the file being edited never named the ADRs that governed it, so the author could not have known. The check is a presence check (does the governed file still reference its ADR ids?), deliberately dumb; the value is that the failure carries the **invariant**, not just an id to paste back, and it fires on exactly the diff that warrants a second look — someone rewriting a governed block and dropping the rationale with it.

.changeset/blueprint-formula-expression.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': minor
+---
+
+A blueprint `formula` field can finally say what it computes: `BlueprintFieldSchema` and its OpenAI-strict mirror both gain `expression`.
+
+`BlueprintFieldSchema.type` is the **full** `FieldType` enum, so the AI-build design step could always NAME a `formula` field — but neither the lenient schema nor the strict mirror the model generates against had any key for the body. There was no way, anywhere on that surface, to state what the formula computed. It materialized bare, and cloud's graph-lint then correctly reported `formula_without_expression` with the fix *"Set field expression to a CEL formula"* — a fix the agent could not write in the blueprint it was holding. Detected, but unfixable on the surface that produced it.
+
+This is the exact hole `summaryOperations` closed for roll-ups in cloud#970 (see this file's own test: *"z.object STRIPS unknown keys, so before this slot existed a blueprint that correctly declared `{ type:'summary', summaryOperations:{…} }` lost the config at the parse waist and materialized runtime-dead"*). `formula` was simply left behind — the same defect, one field type over.
+
+It bites hardest through `nameField`, whose own guidance tells the model to point at a formula for numbered entities (invoice/ticket) that compose `number · name`. Without an expression slot, following that advice produces a record title that is blank on every card, lookup chip and breadcrumb.
+
+**The pin matters more than the key.** A1's root cause is not a forgotten property — it is that two schemas describe the same shape and nothing forced them to agree. The mirror is what the model may EMIT; the lenient schema is what downstream READS. Drift in either direction silently drops authored config. A new test asserts the two field schemas carry **exactly** the same keys, so the next key added to one cannot go missing from the other.
+
+Cloud's `objectBody` carries the value through to materialization (companion change in the `cloud` repo); it reads the key via cast, as it already does for `defaultValue`, so it is inert against an older spec and live as soon as this ships.

.changeset/fix-cross-repo-closer-require.md

@@ -0,0 +1,23 @@
+---
+---
+
+fix(ci): hand the cross-repo token to github-script instead of requiring @actions/github
+
+Release-nothing: touches `.github/workflows/cross-repo-issue-closer.yml` only.
+
+`require('@actions/github')` is not resolvable from a github-script `script:`
+block — the action bundles its dependencies, so the call fails at runtime with
+`MODULE_NOT_FOUND`. The token is now handed to the action itself
+(`github-token:`), which makes the injected `github` client the cross-repo one,
+with `secrets.GITHUB_TOKEN` as the fallback so the report path can still
+comment on the pull request when no cross-repo credential is configured.
+
+Observed in objectui, whose copy of this workflow reached that line first. Its
+run also confirmed the credential logging added alongside works, printing
+`CROSS_REPO_ISSUE_TOKEN: configured` before failing at the require.
+
+This supersedes #4573, which renamed the second client without removing it —
+the rename fixed the identifier collision that aborted parsing, and only then
+did the run get far enough to hit the unresolvable module. Three failures in
+three consecutive runs, each one further down the same script: parse, resolve,
+then (expected next) the API calls themselves.

.changeset/pm-dispatch-escalation-bar.md

@@ -0,0 +1,4 @@
+---
+---
+
+Internal agent tooling only (`.claude/` pm-dispatch escalation bar + API-body generics trap) — releases nothing.

.changeset/save-flow-canonicalization-fallback-warning.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): a flow save that skipped canonicalization says so (#4580)
+
+`saveMetaItem` canonicalizes flow bodies before the schema gate (#4542). When the
+canonicalizer throws — it is stricter than the gate: strict parse, cycle
+detection, control-flow region validation — the save falls back to the raw body
+so a work-in-progress draft with a temporary cycle stays saveable. That fallback
+is correct and unchanged. It was also completely silent.
+
+Of the four postures at this seam, three announce themselves: a clean
+canonicalization heals the row, a refused rename fails with `409
+FLOW_CONVERSION_CONFLICT` naming the token, and a host with no automation service
+is reported by `os migrate meta --stored`. The throw-fallback said nothing, so a
+save that skipped canonicalization was indistinguishable from one that healed the
+row — and a body that is *both* a legacy dialect and unparseable by the strict
+canonicalizer re-persisted verbatim. That is the exact #4542 symptom, arriving
+silently, while the boot warning for legacy stored rows tells the author that
+re-saving is the remedy.
+
+The fallback now emits a `console.warn` naming the flow and the canonicalizer's
+own error, deduped once per flow per process (the `convertStoredItem` pattern —
+Studio autosaves the same draft repeatedly, and a WIP cycle throws on every
+write). This aligns the write seam with ADR-0087 D2's "loud" posture, where
+conversions emit notices, reads warn once per row, and `migrateStoredMetadata`
+reports `failed` with the message.
+
+No behavior change: the body still saves, the schema gate stays the arbiter, and
+`registerFlow` still refuses to arm a malformed flow. Refusing the save in
+publish mode was considered and rejected — publish is the default mode, so it
+would silently tighten validation for every existing caller, and it could only be
+enforced on hosts that have an automation service, making the same body saveable
+on a control-plane host and a 422 on an automation host.

.changeset/webhook-dual-source-api-side.md

@@ -0,0 +1,44 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `@objectstack/spec/api` no longer exports the bare names `WebhookConfig` / `WebhookEvent` — they belong to `./integration` alone (#4572)
+
+The names `WebhookConfig(Schema)` / `WebhookEvent(Schema)` resolved to **two
+different declarations** depending on the import path (`./api` vs
+`./integration`) — the #4411 dual-source trap, and a cross-form one:
+`./api`'s `WebhookEventSchema` was a `z.object` (an OpenAPI 3.1 webhook
+*definition* descriptor: `name`/`description`/`method`/`payloadSchema`/
+`security`) while `./integration`'s is a `z.enum` of connector event types
+(`'record.created'` … `'rate_limit.exceeded'`). Auto-importing the wrong side
+compiled and validated the wrong contract. Resolution (three-repo,
+import-statement-level consumer scan: framework, cloud, objectui):
+
+- **Removed** `WebhookConfigSchema` / `WebhookConfig` from
+  `@objectstack/spec/api`. This pair was dead: wired into nothing — not even
+  `RestServerConfigSchema` — with zero import-level consumers in all three
+  repos, and no runtime ever read a REST-server webhook config.
+  - FROM `import { WebhookConfig } from '@objectstack/spec/api'` →
+    TO: no replacement exists for a REST-server webhook config (it never had a
+    runtime). For a real outbound webhook use `Webhook` from
+    `@objectstack/spec/automation`; for a connector webhook use
+    `WebhookConfig` from `@objectstack/spec/integration` (a **different
+    shape**: it extends the canonical automation `WebhookSchema` with
+    `events` / `signatureAlgorithm`, and has no `deliveryConfig` /
+    `registrationEndpoint` / `enabled`).
+- **Renamed** `WebhookEventSchema` / `WebhookEvent` in `@objectstack/spec/api`
+  → `OpenApiWebhookEventSchema` / `OpenApiWebhookEvent` (same shape, rename
+  only; joins the existing `OpenApi*` family). `OpenApi31ExtensionsSchema.webhooks`
+  now references the renamed schema — its parsed/authored shape is unchanged.
+  - FROM `import { WebhookEvent } from '@objectstack/spec/api'` →
+    TO `import { OpenApiWebhookEvent } from '@objectstack/spec/api'` (if you
+    meant the OpenAPI 3.1 webhook descriptor), or
+    `import { WebhookEvent } from '@objectstack/spec/integration'` (if you
+    meant the connector event enum — check which shape you actually consume:
+    object vs string enum).
+- `@objectstack/spec/integration`'s `WebhookConfig(Schema)` /
+  `WebhookEvent(Schema)` are **unchanged** and are now the sole owners of the
+  bare names. Imports from `./integration` need no migration.
+
+`dual-source-exports.baseline.json` shrinks by exactly these 4 rows (35 → 31,
+#4535 C1).

.claude/agents/os-dev.md

@@ -33,6 +33,23 @@ rules that most often get missed:
    consumer (`??` alias, tolerant parse), the bug is at the producer or in the
    spec — fix it there, or return `needs_decision`.
 
+**Resource discipline — parallel agents share ONE container; unbounded
+build/test runs OOM it.** Binding rules:
+
+1. **Serialize the heavy phase.** Wrap every build and test run in the shared
+   verification lock, so editing parallelizes but memory peaks never stack:
+   `flock -w 7200 /tmp/os-heavy-verify.lock -c '<build/test command>'`
+   (one lock file per container; waiting on it is normal, not a hang).
+2. **Cap the heap.** Prefix heavy commands with
+   `NODE_OPTIONS=--max-old-space-size=4096` (raise only with a reason).
+3. **Scope, don't sweep.** Build and test the affected packages
+   (`pnpm --filter <pkg> build/test`), not the whole repo, unless the task
+   explicitly requires a full pass. Cap test parallelism:
+   vitest `--maxWorkers=2`, turbo `--concurrency=2`.
+4. **Clean up when done**: after the PR is up, remove your worktree
+   (`git worktree remove <path> --force`) — leftover `node_modules` trees
+   exhaust the container's disk, which fails as confusingly as OOM.
+
 Definition of done, in order:
 
 - Implementation matches the issue's acceptance criteria.
@@ -89,3 +106,10 @@ Final message — exactly this JSON, no prose around it:
 
 Use `status: "rework"` for a partial result you know is incomplete (say why in
 `summary`); the PM will review and re-dispatch with feedback.
+
+Practical trap when filing issues/PRs through the GitHub API: the body
+sanitizer strips `<` followed by a letter as an HTML tag **at rest**, which
+destroys TypeScript generics (`Assert<Equal<1, 2>>` is stored as `Assert>`).
+Write generics with a space after each `<` — `Assert< Equal< 1, 2 > >` is
+still valid TypeScript — and read the stored body back to verify when a
+snippet is load-bearing.

.claude/skills/pm-dispatch/SKILL.md

@@ -102,7 +102,23 @@ known case: accepting a `repo:objectui` PR ⇒ file a `pm:queue` issue in
 `objectstack` — "run `pnpm objectui:refresh` and land the console bump",
 referencing the merged PR, blocked-by it until it actually merges.
 
-**4. One board, no second tracker.** The pm labels above are the state
+**4. Multiple PM sessions shard by repo — never share one queue.** The
+claim protocol makes concurrent PMs *safe*, not *useful*: batch
+independence (file-disjointness) is only checked within one PM's view, so
+two PMs on the same queue can claim different issues that collide on
+shared files, and the merge queue is one lane regardless. Scaling order:
+
+1. One PM, bigger batch (`batch:5` is the maintainer's chosen operating
+   point, riding on the resource discipline above), heavy tasks via
+   `mode:cloud` — adds compute without adding schedulers.
+2. When one PM genuinely can't keep up: a second session takes a **whole
+   repo** as its shard (`/pm-dispatch repo:objectstack-ai/objectui`) —
+   file universes are disjoint by construction. A sharded PM states its
+   shard in every claim comment and **never claims outside it**; cross-repo
+   parent/sub-issue chains stay with the main-backlog PM.
+3. Multiple PMs on the SAME queue: prohibited — all cost, no throughput.
+
+**5. One board, no second tracker.** The pm labels above are the state
 machine; an org-level GitHub Project pulling issues/PRs from all three repos
 gives the maintainer a single view (filter by `repo:*` and `pm:*`). The PM
 maintains no tracking state outside GitHub — that invariant is what keeps
@@ -201,6 +217,16 @@ execute atomically, in order:
 Dev agents push their branch early — a remote branch is the hardest evidence
 of work in flight, closing the gap between "claimed" and "PR exists".
 
+**Multiple GitHub accounts (colleagues' Claude Code sessions) simplify
+this, not complicate it.** Across accounts the assignee alone already says
+*who*: `assignee isn't you → taken, never touch` is the entire cross-account
+protocol, and it's already the rule. The claim-comment ritual (branch name,
+round, race check) matters *within* one account's sessions. When several
+accounts work the backlog, partition it the same way as multi-PM sharding —
+by repo or by an agreed label per account — and record the assignment table
+once in a pinned issue or the round report so nobody triages another
+account's shard.
+
 **Stale-claim reclaim**: a claim older than ~24 h whose promised branch does
 not exist on the remote and has no PR is presumed dead — comment asking, and
 after another window of silence, remove the assignee (note why) and return
@@ -242,6 +268,19 @@ Follow your operating procedure (you are the os-dev agent). Non-negotiables:
 Return ONLY the JSON report defined in your agent definition.
 ```
 
+#### Resource limits — parallel agents share ONE container
+
+Memory peaks come from **build + test**, not editing, so the fix is not less
+parallelism but serialized heavy phases: the os-dev definition requires every
+build/test run to hold the container-wide verification lock
+(`flock /tmp/os-heavy-verify.lock`), a `NODE_OPTIONS=--max-old-space-size`
+heap cap, scoped `--filter` builds/tests, capped vitest/turbo workers, and
+worktree cleanup after the PR is up. PM-side: treat `batch:3` as assuming
+normal-sized tasks — for build-heavy ones (dependency-family upgrades, full
+regression passes) drop to `batch:2`, or dispatch that issue via
+`mode:cloud` so it gets its own container. If an agent dies with a
+heap/OOM signature, redispatch it alone rather than into a full batch.
+
 #### Dispatch backends
 
 **`mode:subagent` (default).** The `Agent` tool, as described above. The devs
@@ -313,8 +352,36 @@ Verdict per issue:
 
 ### 8. Escalate uncertainties to the maintainer
 
-Whenever a dev returns `needs_decision`, an issue is too vague to dispatch, or
-rework has failed twice:
+**First, apply the escalation bar — most things that FEEL like decisions are
+not.** The maintainer's words: 「明显的问题直接修,不是事事都需要我确认」.
+Escalate ONLY when at least one of these holds:
+
+- the options genuinely diverge on **product semantics or public contract
+  shape** and neither the issue, AGENTS.md, ADRs, nor existing code norms
+  determines the answer;
+- the fix requires a **destructive or hard-to-reverse action** (stored-data
+  migration shape, deleting a shipped capability, force operations).
+
+Everything else is the PM's call — decide, dispatch, and give the maintainer
+a **veto window instead of a permission gate**: state what you decided and
+why in the issue comment and the round report; they can stop it, but you do
+not wait for them. Named non-escalation classes (act immediately):
+
+- **Restore-invariant fixes.** When the repo already states the invariant —
+  one contract version across the family, declared = enforced, a gate must
+  actually compile/run what it claims to check — a finding that the
+  invariant is broken carries its own decision. A dual-version dependency
+  graph, an inert tripwire, an unwired gate: queue it, dispatch it, report
+  it. Asking "may I restore the invariant?" is the anti-pattern.
+- **Sequencing and dependency ordering** between technical tasks.
+- **Verification strategy** (what regression pass a risky-but-decided change
+  needs) — that is scoping the work, not deciding it.
+- A dev's `needs_decision` that, on PM review, falls into the classes above:
+  answer the dev yourself with the decision and rationale; do not relay it
+  upward.
+
+Whenever a dev returns `needs_decision` that passes the bar above, an issue
+is too vague to dispatch, or rework has failed twice:
 
 1. **Default: the decision lives ON the issue it belongs to — never a new
    issue.** Post the analysis as a comment on that issue, add the

.github/workflows/cross-repo-issue-closer.yml

@@ -46,6 +46,12 @@ jobs:
           # to the repository running the workflow, which is the whole problem.
           CROSS_REPO_TOKEN: ${{ secrets.CROSS_REPO_ISSUE_TOKEN }}
         with:
+          # Hand the cross-repo token to the action itself, so `github` IS the
+          # cross-repo client. `require('@actions/github')` does NOT work here:
+          # github-script bundles its dependencies and the module is not
+          # resolvable from the script scope (`MODULE_NOT_FOUND`). Falling back
+          # to GITHUB_TOKEN keeps the report path able to comment on this PR.
+          github-token: ${{ secrets.CROSS_REPO_ISSUE_TOKEN || secrets.GITHUB_TOKEN }}
           script: |
             const body = context.payload.pull_request.body || '';
             const prUrl = context.payload.pull_request.html_url;
@@ -109,27 +115,23 @@ jobs:
               return;
             }
 
-            // A second client: `github` is bound to GITHUB_TOKEN, which has no
-            // write access outside this repository.
-            const crossRepo = require('@actions/github').getOctokit(token);
-
             for (const [key, t] of targets) {
               try {
-                const { data: issue } = await crossRepo.rest.issues.get({
+                const { data: issue } = await github.rest.issues.get({
                   owner: t.owner, repo: t.repo, issue_number: t.number,
                 });
                 if (issue.state === 'closed') {
                   core.info(`${key} is already closed — skipping.`);
                   continue;
                 }
-                await crossRepo.rest.issues.createComment({
+                await github.rest.issues.createComment({
                   owner: t.owner, repo: t.repo, issue_number: t.number,
                   body:
                     `已由 ${thisRepo} 的 ${prUrl} 修复并合并。\n\n` +
                     `（跨仓库的关闭关键字不会自动生效，本条由 \`cross-repo-issue-closer\` 工作流代为收口。）\n\n` +
                     `---\n_Generated by [Claude Code](https://claude.ai/code)_`,
                 });
-                await crossRepo.rest.issues.update({
+                await github.rest.issues.update({
                   owner: t.owner, repo: t.repo, issue_number: t.number,
                   state: 'closed', state_reason: 'completed',
                 });