docs(agents): qualify line 8's DB-column item — control plane vs. the metadata tables

[claude]

Fixes #13368

Governed surface (AGENTS.md) — draft, human merge. Never flipped ready, never queued, never auto-merge-armed.

What changed — one item inside line 8, line-neutral

AGENTS.md:8 lists five flagship surfaces of the v5.0 project to environment rename and closes with "No aliases." Only the DB-column item moves; the rename statement itself is untouched.

Before:

..., `OS_ENVIRONMENT_ID`, DB column `environment_id`). No aliases.

After:

..., `OS_ENVIRONMENT_ID`, DB column `environment_id` [control-plane tables; on the metadata tables since deprecated in favour of `organization_id`, ADR-0006 v4]). No aliases.

Why that shape, and not either of the two the card offered

The card fenced the work as investigation first, then the smaller of (a) qualify the item or (b) drop it. The persistence-layer census says the item is under-qualified in both directions, and the two errors point opposite ways — so a flat "since deprecated" (a) and a deletion (b) would each teach one of them.

Census — which tables still carry environment_id

Table / schema	State on origin/main	Evidence
sys_environment_member (control plane)	LIVE and enforced — keyed (environment_id, user_id); the runtime dispatcher filters on it for the per-project membership 403 gate	packages/runtime/src/http-dispatcher.ts:1145; ADR-0002 line 41
sys_package_installation (control plane)	LIVE — records which packages are installed in which environment	ADR-0002 line 42; ADR-0003 lines 90, 100
sys_metadata	DECLARED, deprecated — nullable legacy lookup labelled "Environment (deprecated)"; explicitly excluded from the ADR-0048 uniqueness discriminator	packages/metadata-core/src/objects/sys-metadata.object.ts:138-148, 206
sys_metadata_history	DECLARATION REMOVED — keyed (organization_id, type, name) only since the ADR-0008 section-0 branch/project-removal amendment	packages/metadata-core/src/objects/sys-metadata-history.object.ts:17-21
sys_activity (plugin-audit)	declared and indexed, not marked deprecated, and never written — filed separately, see below	packages/plugins/plugin-audit/src/objects/sys-activity.object.ts:264, 287
tenant / environment DB generally	by design zero environment_id columns — the environment is implicit in the connection	ADR-0002 line 58

Census — is any NEW writer left on the metadata tables?

No. Measured, not recalled:

• Zero non-comment source lines write environment_id onto sys_metadata. The only remaining metadata-layer touch is a backwards-compat read mapping, packages/metadata/src/loaders/database-loader.ts:702.
• DatabaseLoader's environmentId option is accepted for back-compat and ignored: "writes do not set environment_id and filters do not constrain on it" (database-loader.ts:75-85).
• That is mechanically pinned, not merely documented — packages/metadata/src/loaders/database-loader.test.ts:403-425 asserts the create call carries organization_id and not environment_id, and that no findOne where-clause has the property.
• ⚠️ Stale prose found on the way: packages/metadata-protocol/src/protocol.ts and packages/objectql/src/plugin.ts still describe saveMetaItem "stamping" environment_id. Those files carry zero non-comment occurrences of the column — the comments describe a writer that no longer exists. Out of scope for this PR; filed separately.

Why the rename statement stays

The v5.0 project_id to environment_id rename really happened and its terminal migration is still shipped — packages/metadata/src/migrations/migrate-project-id-to-environment-id.ts, whose table list is derived from the declarations that still carry the target column. The deprecation sits on a later and different axis (environment to organization), which is why the qualification is additive and time-marked ("since deprecated") rather than a rewrite of the rename.

Landing constraints — re-derived, not recalled

The dispatch flagged uncertainty about which width gate binds line 8. Re-derived from the gate's own output and its own exported scanners:

Ratchet leg	Binds line 8?	Reading at head 09f0689d0
line-count ceiling	YES — the only binding one	AGENTS.md is 1162 lines (ceiling 1162; headroom 0)
widest-table-row pin (1081)	no	line 8 is a blockquote, not a table row; the widest row is at L720, untouched: widest table row is 1081 bytes (pin 1081; headroom 0)
120-byte line rule	no	line 8 is structurally exempt as blockquote; scanLineLengths reports 0 offenders

So the edit had to be line-neutral and byte growth inside line 8 is unmetered. Measured: git diff --numstat is 1 1 AGENTS.md; the file stays at 1162 lines; line 8 grew 257 to 365 bytes. No ceiling was raised and no pin was touched.

Reverse verification (predicted direction stated before running; both legs restored from HEAD and proven byte-identical — git diff HEAD empty and git hash-object equal to the HEAD blob 8802388ed5bd3fafd363108cb3724dd95a5848ce):

1. Append one line, so 1163 — predicted RED on the ceiling. Observed: AGENTS.md is 1163 lines; the ratchet ceiling is 1162, exit 1. The row pin stayed green.
2. Strip line 8's leading blockquote marker — predicted RED on the 120-byte rule. Observed: AGENTS.md has 1 line(s) over the 120-byte budget: L8 (369B), exit 1. This proves the gate reads this edited line 8, and that the structural blockquote exemption is what keeps it green — not slack.

Post-restore the gate returns exit 0 with both AGENTS.md verdict lines green.

Same-day churn

Based on c813e7ac7 (PR #13403, merged 11:22:59Z), which touched Prime Directive 11 near L232 and section 9 near L394. This diff is line 8 only — disjoint from both. The check:pm-governed-prose pinned region on this file is Prime Directive 14, L274 to L331 — also disjoint, and the gate is green.

Gates — the derived family, all green at head 09f0689d0, clean tree

Derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no hand-written path list; the script took the change set from the merge base itself). Its eight families match the dispatch list exactly. Exit codes captured before any pipe.

check:agent-test-spelling      EXIT=0
check:docs-audit-scope         EXIT=0
check:pm-governed-merges       EXIT=0
check:pm-governed-prose        EXIT=0
check:pm-skill-id-lint         EXIT=0
check:pm-skill-ratchet         EXIT=0
check:required-contexts        EXIT=0
check:nul-bytes                EXIT=0
node scripts/check-required-contexts.mjs   EXIT=0

Gate verdict lines, quoted from the gates themselves:

• check-skill-line-ratchet: AGENTS.md is 1162 lines (ceiling 1162; headroom 0).
• check-skill-line-ratchet: AGENTS.md: widest table row is 1081 bytes (pin 1081; headroom 0).
• check-governed-prose: 2 instruction surface(s) name all 5 registered governed surfaces (docs/adr/** · .claude/** · skills/** · AGENTS.md · CLAUDE.md) and claim no others.
• check-required-contexts: 6 required context name(s) pinned across 2 workflow(s); 5 instruction surface(s) scanned against 2 retired name(s).
• check-nul-bytes: OK (scanned 7438 text file(s) ... no raw ASCII control bytes).

⚠️ One not-a-measurement worth recording: on a fresh worktree check:required-contexts first exited 1 with PREREQUISITE NOT MET — the dependency yaml is not installed. That is the gate declining to run, not a finding. Re-run after pnpm install: exit 0, quoted above.

Changeset

None, deliberately — the diff is AGENTS.md only and publishes nothing from any package. This follows the precedent set by PR #13403 on this exact surface (AGENTS.md + CLAUDE.md, no changeset, labelled skip-changeset). The skip-changeset label is applied to this PR; if the Check Changeset gate disagrees, that verdict wins and a changeset gets added.

Out of scope — filed, not fixed here

Two findings surfaced by the census; both are separate defect classes and neither is touched by this diff. They are listed in the report comment on #13368 with their filing state.

Generated by Claude Code

---

Generated by Claude Code