Skip to content

Commit e4a770d

Browse files
docs(governed): record the allowOrgOverride → allowEnvironmentOverlay rename in AGENTS.md rule 7, the objectstack-ai skill and the ADR-0005 / ADR-0010 headers (#22340 S3) (#23011)
Part of #22340 (S3) Clause-②: no S3 of #22340 — the governed-text half of the `allowOrgOverride` → `allowEnvironmentOverlay` rename. S2 (the key, its tombstone, the retired-keys entry, the D3 semantic entry and the `/meta/types` wire field) landed in PR #22874 (`e23eccb164`); this PR records that landed decision in governed text and changes no semantics. Ruling followed: `6073921182` (Q1 A · Q2 A, maintainer 「同意」); shape: triage `6121122315` — the two normative lines edited in place, a header amendment note on each ADR, history lines untouched, no residue. The card stays open for cloud's two test helpers. Five files, 22 changed lines (+18 / −4): four governed paths and one changeset — Tier H, draft only; an authorized APPROVED review lands it. Session `session_01CinRQcE6T8SvMbhH8D3NhS`, dispatched under claim `6121201470`. ## Per-file before / after ### `AGENTS.md` rule 7 (lines 191–192) — in place, same line count Before: ```text `packages/spec/src/{domain}/`. Org overlay opt-in lives only in `allowOrgOverride` on `DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005. ``` After: ```text `packages/spec/src/{domain}/`. Environment-overlay opt-in lives only in `allowEnvironmentOverlay` on `DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005, amended by ADR-0131 C5. ``` Line ratchet (`check:pm-skill-ratchet`): `AGENTS.md is 1109 lines (ceiling 1116; headroom 7)` before and after; `AGENTS.md: widest table row is 768 bytes (pin 768; headroom 0)` before and after (rule 7 is a list item, not a table row). Net lines: 0. No issue or PR number added (`check:pm-skill-id-lint`: 34 files clean). ### `skills/objectstack-ai/SKILL.md` line 347 — in place Before: `` `allowOrgOverride:false`; ADR-0063 §2) and `os g agent` is retired: a `` After: `` `allowEnvironmentOverlay:false`; ADR-0063 §2) and `os g agent` is retired: a `` Token ratchet (`check:skills-token-ratchet`): `skills/objectstack-ai/SKILL.md is 5540 tokens (ceiling 6806; headroom 1266)` before → `5541 tokens (ceiling 6806; headroom 1265)` after; no ceiling moved, no deletion needed. Lines: 421 → 421 (the file), 4409 → 4409 (all ten `skills/*/SKILL.md` summed); authored bundle total 144143 → 144144 tokens against a 154938 ceiling sum. Net lines for `skills/**`: 0. The new key is live in the implementation index (`check:skill-identifier-liveness` green). No issue or PR number in `skills/**`. ### `docs/adr/0005-metadata-customization-overlay.md` — a note at the top, an `Amended by` entry Added under the existing 「v5.0 update (2026)」 blockquote, in the same voice: > **Protocol 18 update (2026-10-12, ADR-0131 C5, #22340):** The per-type overlay opt-in on `MetadataTypeRegistryEntry` is spelled `allowEnvironmentOverlay` from protocol 18 (`packages/spec/src/kernel/metadata-plugin.zod.ts#allowEnvironmentOverlay`). [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) D6 retired the per-organization overlay axis, so the key now names the one scope it governs — whether an environment may overlay an item of this type that a managed package ships. The old key `allowOrgOverride` stays on the registry entry schema only as a tombstone that refuses at parse with the new name in its prescription: no second key, no alias, no conversion. The lines below that name `allowOrgOverride` describe the field as it was spelled when they were written and are preserved verbatim. Appended to the `**Amended by**:` status line: `, [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) C5 / D6 (the per-organization overlay axis is retired and the per-type opt-in is spelled `allowEnvironmentOverlay` from protocol 18 — the note at the top of this record)`. The body lines that name `allowOrgOverride` are untouched — 12 matching lines at BASE (`:47`, `:68`, `:515`, `:518`, `:521`, `:537`, `:596`, `:704`, `:707`, `:718`, `:719`, `:728`; the dispatch counted 13), each now two lines lower. ### `docs/adr/0010-metadata-protection-model.md` — the same note, a new `Amended by:` header line The note is the ADR-0005 text verbatim (one decision, recorded twice). The header block gains, after `**Builds on:**` and in the block's own `**Key:** value` style: `**Amended by:** [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) C5 / D6 (the per-organization overlay axis is retired and the type-level opt-in is spelled `allowEnvironmentOverlay` from protocol 18 — the note at the top of this record)`. Its nine body lines naming the old key (`:19`, `:31`, `:94`, `:119`, `:122`, `:190`, `:297`, `:525`, `:605` at BASE) are untouched, each now three lines lower. ### `.changeset/22340-s3-governed-text-rename.md` `'@objectstack/skills': patch` — `skills/**` ships as `@objectstack/skills` (`packages/skills/package.json`; in the `fixed` group of `.changeset/config.json`; `.changeset/pre.json` is mode `pre`, tag `next`; precedent PR #22846 for #22825). No `skip-changeset`. `AGENTS.md` and `docs/adr/**` publish nothing. ## Premises checked against `origin/main` `74c4b3435` (BASE) - `git grep -n allowOrgOverride` over the four files answers `AGENTS.md:191`, `skills/objectstack-ai/SKILL.md:347`, ADR-0005 × 12 lines, ADR-0010 × 9 lines — the sites the dispatch named (ADR-0005: 12 lines, not 13). After this PR: 0, 0, 13 (12 history lines + the note), 10 (9 + the note). - `allowEnvironmentOverlay` is declared in `packages/spec/src/kernel/metadata-plugin.zod.ts` (the `z.object` key, the `allowOrgOverride` tombstone beside it, `DEFAULT_METADATA_TYPE_REGISTRY` reading it); the notes anchor it as a symbol anchor, which `check:adr-symbol-anchors` accepts as a declaration site (2319 anchors across 142 records, 0 unresolved). - No open PR and no in-flight claim touches the four files; `origin/main` moved two commits between BASE and the merge below (`147a0d1ac`, `6a7eca686`) and touched none of them. ## Gates — run on the final commit `7362ce1` (`5963d2cf6` merged with `origin/main` `6a7eca686`) `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derives 53 commands for the 5 paths (41 at claim time on the four files; the changeset path adds the changeset families). Each was run with stdout and stderr redirected into its own log file and its exit code captured before any pipe, and `--ran` reconciled the record: **53 derived, 51 run at exit 0, 2 NOT MEASURED, 0 unrun** (`✓ dispatch-gates --ran: 53 derived famil(ies) accounted for — 51 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3)`). Verdict lines from the `7362ce1` run: - `✓ check-skill-line-ratchet: AGENTS.md is 1109 lines (ceiling 1116; headroom 7).` · `✓ check-skill-line-ratchet: AGENTS.md: widest table row is 768 bytes (pin 768; headroom 0).` - `✓ check-skills-token-ratchet: skills/objectstack-ai/SKILL.md is 5541 tokens (ceiling 6806; headroom 1265).` · `✓ check-skills-token-ratchet: 54 authored bundle file(s) within their ceilings; 10 generator-owned file(s) measured, not ratcheted.` - `✓ check-skill-id-lint: 34 file(s) clean (pattern /#[0-9]{3,}/g).` - `check-skill-identifier-liveness OK — Leg 1: 457 citation(s) over 53 published file(s) checked against 126987 implementation word tokens (0 ledgered exemption(s)); Leg 2: 8 registered exhaustive section(s), 0 ledgered gap(s).` - `✅ check-adr-symbol-anchors: 2319 anchors across 142 records resolve — 439 symbol (412 declaration, 27 literal), 1853 file-level, 27 cross-repo, 6 exempt, 18 continuation.` - `✅ check-adr-links: 730 relative link destination(s) under docs/adr/ resolve` - `check-adr-anchors: OK (68 anchored file(s), every governing ADR still referenced; 136 decision number(s), each naming one decision or an allowlisted pair; 44050 citation(s) across 5831 file(s) resolve; 1624 decision-letter citation(s) on the anchored surface name a decision the record makes).` - `✓ check-governed-prose: 2 instruction surface(s) name all 6 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md · docs/NORTH-STAR.md) and claim no others.` - `check-nul-bytes: OK (scanned 11012 text file(s) -- 11012 tracked, 0 untracked-not-ignored; skipped 9 binary; no raw ASCII control bytes).` - `✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added).` · `✓ This diff introduces no major bump.` - `✅ Skill docs in sync` (`check:skill-docs`, frontmatter unchanged) · `✓ check:doc-formula-expressions: 22 record-scoped formula example(s) across 473 files / 1388 TS blocks judged clean by @objectstack/formula.` — measured after building `@objectstack/formula` and `@objectstack/lint` (with their closure: spec, types) under the shared verify lock (`os-verify-lock: VERDICT command-exit 0 · held the lock 115s`). - `check-dts-closure: 4 built package(s) swept - 46/46 declared declaration file(s) present across 4 package(s)` and `check-sourcemap-no-sources-content: 4 built package(s) swept - 58 map(s), none embed source text` — sweeps over the four packages that build left, not closure readings. **NOT MEASURED (declared, not green):** `pnpm check:dual-build-cjs-loads` and `pnpm check:lean-entry-closure` exited 3 (`PREREQUISITE NOT MET`): the first loads the built `exports` of every workspace package (107 without a `dist/`), the second `@objectstack/objectql`'s built entry points. This diff changes no file any package build reads — no `packages/**` source, manifest or tsconfig; `@objectstack/skills`'s build is a byte copy of `skills/**` that emits no entry point, declaration or map — so the repo-wide build those two need is CI's run (`Build Core`, `Lint & Repo Gates`), not a local one. `pnpm lint` (repo-wide eslint) is likewise CI's: the diff has no lintable file. No package `test` / `typecheck` is owed (no package source changed); the `packages/cli` tiers do not apply. ## Sibling `#22998` (`AGENTS.md`: the merge-queue required-set paragraph and the gates section) Not landed at my last merge of `origin/main` (`6a7eca686`, 2026-10-12T09:26Z): `git log 74c4b34..origin/main --grep=22998` is empty, and `git diff 74c4b34 origin/main -- AGENTS.md` is empty. Region-disjoint from rule 7; if a later merge conflicts on `AGENTS.md`, both intents are kept. ## Acceptance notes (observations; nothing filed) - `scripts/adr-anchors/packages__spec__src__kernel__metadata-plugin.zod.ts.json` cites `docs/adr/0005-metadata-customization-overlay.md:53-64` (the whitelist table) in its `invariant` prose; the two-line note at the top of ADR-0005 moves that table to lines 55–66. No gate reads that range (`check:adr-anchors` verifies ADR ids and decision letters; `check:adr-symbol-anchors` sweeps `docs/adr/**`, not `scripts/adr-anchors/**`), and the file is outside this PR's governed-only surface. Carrier: the next PR that edits that anchor file. Not filed. - ADR-0063 line 135 (its §2 checklist, which the skill line cites) still spells the key `allowOrgOverride:false` — a history line of the class the triage left as written; the skill cites the decision, not the spelling. Not edited, not filed. ## 维护者速读(草稿) **改了什么**:把「某类元数据能不能被环境覆盖」这个按类型的开关,在四份给 AI 和人读的治理文本里改成代码里现在的名字 `allowEnvironmentOverlay`(旧名 `allowOrgOverride`):AGENTS.md 第 7 条规则、对外发布的 `objectstack-ai` 技能里的一行,ADR-0005 与 ADR-0010 各在顶部加一段「协议 18 起改名」的说明并登记被 ADR-0131 修订;两份 ADR 正文里描述当年字段的历史叙述原样保留。另附一条 `@objectstack/skills` 的 patch changeset,因为那一行是随技能包发布的。 **为什么改**:改名本身(S2,PR #22874)已经合入,代码、类型和 `/meta/types` 返回都只认新名,旧名写出来会在解析时被拒绝并提示改名。但 AGENTS.md 和发布的技能还在教旧名 —— AI 照文档写出来的键会被运行时拒收,正是「文档与契约不一致」这类事故的源头。ADR 是决策档案,按 ADR-0005 自己已有的惯例(顶部的「v5.0 update」注)只加注、不改写历史。 **风险与代价(含回滚)**:零运行时风险 —— 不改任何代码、schema 或行为,只改文字。本地门禁 53 项中 51 项通过,2 项需要整仓构建、留给 CI 测量。代价是 `@objectstack/skills` 下个版本多一条 patch 条目。回滚:revert 本 PR 即可,无数据、无迁移。 **席位意见**: **你要做的**:这是 Tier H 治理面(AGENTS.md、skills/**、docs/adr/**),需要你或 `GOVERNED_APPROVERS` 中的授权账号在本 PR 上给一个 APPROVED review,之后由席位合入。确认两点即可:① 新名字 `allowEnvironmentOverlay` 与 S2 落地的一致;② ADR 顶部加注的写法(照 ADR-0005 的「v5.0 update」样式)你认可。 --- _Generated by [Claude Code](https://claude.ai/code/session_01CinRQcE6T8SvMbhH8D3NhS)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5dda600 commit e4a770d

5 files changed

Lines changed: 18 additions & 4 deletions

File tree

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): the `objectstack-ai` skill names the `agent` type's environment-overlay switch by its protocol-18 spelling, `allowEnvironmentOverlay:false` (#22340 S3)
6+
7+
Clause-②: no
8+
9+
`skills/objectstack-ai/SKILL.md`'s "Platform agents — reference only" section said the `agent` type is closed with `allowOrgOverride:false`. That key was renamed to `allowEnvironmentOverlay` in protocol 18 (ADR-0131 D6 retired the per-organization overlay axis, so the key names the one scope it governs; the old key stays on the registry entry schema only as a tombstone that refuses at parse with the new name in its prescription), so the published line now reads `allowEnvironmentOverlay:false`. The value, the `allowRuntimeCreate:false` beside it and the ADR-0063 §2 citation are unchanged; nothing an author writes changes. The same rename is recorded in `AGENTS.md` rule 7 and as header amendment notes on ADR-0005 and ADR-0010, none of which publishes.

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -188,8 +188,8 @@ localStorage / auth gotchas.
188188
**Never** set `namespace` (deprecated) or `tableName` (always equals `name`). For module prefixes, embed in the name
189189
(`sys_user`, `ai_conversations`).
190190
7. **One Zod source per metadata type.** Each type (`view`, `flow`, `agent`, …) has exactly one schema in
191-
`packages/spec/src/{domain}/`. Org overlay opt-in lives only in `allowOrgOverride` on
192-
`DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005.
191+
`packages/spec/src/{domain}/`. Environment-overlay opt-in lives only in `allowEnvironmentOverlay` on
192+
`DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005, amended by ADR-0131 C5.
193193
8. **North Star alignment.** Read `content/docs/concepts/north-star.mdx` before structural changes. If a change doesn't
194194
advance §7 Built, shrink Drift, or unlock Missing — it probably shouldn't ship.
195195
9. **`OS_` env-var prefix + structure.** All ObjectStack-owned env vars MUST start with `OS_`, then follow

‎docs/adr/0005-metadata-customization-overlay.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,13 @@
22

33
> **v5.0 update (2026):** Throughout this document, the term *project* has been renamed to *environment* (no aliases; CLI flags, URL paths, schemas, env vars all hard-renamed). See [ADR-0006 v4 — the v5.0 rename and its no-alias decision](./0006-project-environment-split.v4.md#the-v50-rename-and-its-no-alias-decision) for the rationale. The body below is preserved verbatim for historical context.
44
5+
> **Protocol 18 update (2026-10-12, ADR-0131 C5, #22340):** The per-type overlay opt-in on `MetadataTypeRegistryEntry` is spelled `allowEnvironmentOverlay` from protocol 18 (`packages/spec/src/kernel/metadata-plugin.zod.ts#allowEnvironmentOverlay`). [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) D6 retired the per-organization overlay axis, so the key now names the one scope it governs — whether an environment may overlay an item of this type that a managed package ships. The old key `allowOrgOverride` stays on the registry entry schema only as a tombstone that refuses at parse with the new name in its prescription: no second key, no alias, no conversion. The lines below that name `allowOrgOverride` describe the field as it was spelled when they were written and are preserved verbatim.
6+
57

68
**Status**: Accepted (2026-05-16) · **Amended** (2026-05-22, see "Amendment: post-ADR-0006 v4 scope") · **Amended** (2026-04-13, branch concept removed — see [ADR-0008 §0](./0008-metadata-repository-and-change-log.md#0-2026-04-13-amendment--drop-project-and-branch-from-metaref)) · **Amended** (2026-08-09, #6825 — the Phase-1 overlay-index migration is deleted; see "Amendment (2026-08-09, #6825): overlay-index delivery after the Phase-1 migration was deleted") · **Amended** (2026-09-04, [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) D6 — the per-organization overlay axis is **retired for now**: `sys_metadata` carries no organization column, org-scoped writes of the five tier-A types are refused, and the environment layer is the whole ledger; the environment → code layered resolution and the "no overlay row = the registry" reading are unchanged) · **Amended** (2026-09-30, #20051 ruling 甲 — in "Addendum — 2026-05-16 (c)", which code cites as appendix (c), the persisted document is the **parsed body** once every round-trip key is declared, reversing the verbatim `request.item` save; a stored `view` row's round-trip keys are declared, and the storage switch itself, the ruling's last stage, is in force for `view` since PR #20868 (`9905e61ca2`) — see the amendment notes under that addendum's persisted-document bullet) · **Amended** (2026-09-30, #20051 ruling B — the parsed body a `view` stores is the parsed value of every key its request body carried, not the whole parse output: undeclared keys dropped, schema defaults not materialised, a moved key stored under its canonical spelling; every other type still stores its request body — see the second amendment note under that bullet)
79
**Deciders**: ObjectStack Protocol Architects
810
**Builds on**: [ADR-0003](./0003-package-as-first-class-citizen.md) (Package as first-class citizen), [ADR-0004](./0004-cloud-multi-kernel.md) (Cloud + per-project kernels)
9-
**Amended by**: [ADR-0006 v4](./0006-project-environment-split.v4.md) (drops `sys_project` entirely), [ADR-0008](./0008-metadata-repository-and-change-log.md) (re-expresses overlay as `LayeredRepository`; subsequently drops `project`/`branch` from `MetaRef`), [ADR-0029 D9](./0029-kernel-object-ownership-and-platform-objects-decomposition.md#amendment-2026-08-09-6853-a-tenant-overlay-of-an-object-is-its-own-contributor-layer-not-a-second-own) (for `object` only: the overlay is a registry contributor LAYER over the packaged owner, resolved as `base = overlay ?? own`, instead of a destructive in-place overwrite)
11+
**Amended by**: [ADR-0006 v4](./0006-project-environment-split.v4.md) (drops `sys_project` entirely), [ADR-0008](./0008-metadata-repository-and-change-log.md) (re-expresses overlay as `LayeredRepository`; subsequently drops `project`/`branch` from `MetaRef`), [ADR-0029 D9](./0029-kernel-object-ownership-and-platform-objects-decomposition.md#amendment-2026-08-09-6853-a-tenant-overlay-of-an-object-is-its-own-contributor-layer-not-a-second-own) (for `object` only: the overlay is a registry contributor LAYER over the packaged owner, resolved as `base = overlay ?? own`, instead of a destructive in-place overwrite), [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) C5 / D6 (the per-organization overlay axis is retired and the per-type opt-in is spelled `allowEnvironmentOverlay` from protocol 18 — the note at the top of this record)
1012
**Consumers**: `@objectstack/objectql`, `@objectstack/runtime`, `@objectstack/rest`, `apps/studio`, all customer-facing tenants
1113

1214
> **2026-04-13 note** — overlays are keyed exclusively by `organization_id`.

‎docs/adr/0010-metadata-protection-model.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
# ADR-0010: Metadata Protection Model
22

3+
> **Protocol 18 update (2026-10-12, ADR-0131 C5, #22340):** The per-type overlay opt-in on `MetadataTypeRegistryEntry` is spelled `allowEnvironmentOverlay` from protocol 18 (`packages/spec/src/kernel/metadata-plugin.zod.ts#allowEnvironmentOverlay`). [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) D6 retired the per-organization overlay axis, so the key now names the one scope it governs — whether an environment may overlay an item of this type that a managed package ships. The old key `allowOrgOverride` stays on the registry entry schema only as a tombstone that refuses at parse with the new name in its prescription: no second key, no alias, no conversion. The lines below that name `allowOrgOverride` describe the field as it was spelled when they were written and are preserved verbatim.
4+
35
**Status:** Proposed
46
**Date:** 2026-05-29
57
**Supersedes:** —
68
**Builds on:** ADR-0005 (Metadata Customization Overlay), ADR-0008 (Metadata Repository & Change Log), ADR-0009 (Execution-Pinned Metadata)
9+
**Amended by:** [ADR-0131](./0131-total-organization-ownership-no-null-organization-id.md) C5 / D6 (the per-organization overlay axis is retired and the type-level opt-in is spelled `allowEnvironmentOverlay` from protocol 18 — the note at the top of this record)
710

811
---
912

‎skills/objectstack-ai/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -344,7 +344,7 @@ business logic as **AI-exposed Actions**, wire domain knowledge through
344344
## Platform agents — reference only ☁️
345345

346346
The `agent` type is **closed** to third parties (`allowRuntimeCreate:false`,
347-
`allowOrgOverride:false`; ADR-0063 §2) and `os g agent` is retired: a
347+
`allowEnvironmentOverlay:false`; ADR-0063 §2) and `os g agent` is retired: a
348348
stack-authored agent is filtered out of `listAgents()`, refused outright by
349349
`loadAgent()`, and 404s on chat. You extend the platform with **skills**, never
350350
by adding an agent. `AgentSchema`'s full field list is in

0 commit comments

Comments
 (0)