docs(skills): objectstack-ai says agent memory is enforced by the AI runtime, not declared only (#21652)

Fixes #21415

Clause-②: no

## What changed

`skills/objectstack-ai/SKILL.md`, Common Pitfalls 1, told an AI author
that `memory` is "declared only — no runtime reads it". Since the agent
memory contract landed on `main` (spec commit 22c2d6f, ruling A′ on
#20274), that sentence is false in the published catalog, and the open
Version Packages PR (#21352) ships that contract in the next release —
the skill must not go out contradicting it.

One clause is rewritten; nothing else in the pitfall changes. The new
text states the three facts the contract makes true and keeps the
pitfall's point that none of this is a gate:

- `memory` is enforced by the AI runtime ☁️ — long-term notes are
recalled and reflected on;
- `maxEntries` and `reflectionInterval` are required once
`longTerm.enabled` is true;
- there is no storage backend to choose.

The sentence that follows ("For a gate that is **enforced**, use …") is
untouched. The three other `memory` mentions in the file (:218–247) are
the knowledge adapter id `'memory'`, a different thing, and are left
alone.

## Evidence read from the spec (at `origin/main` 15fe567,
`packages/spec/src/ai/agent.zod.ts`)

- :185–188, header comment: "The one runtime that executes agents,
cloud's AI service, enforces long-term memory from `enabled`,
`maxEntries` and `reflectionInterval`".
- :196 `LONG_TERM_STORE_RETIRED`: "`agent.memory.longTerm.store` was
removed in @objectstack/spec 17.7.0 (ADR-0049 enforce-or-remove) — the
memory store is platform infrastructure, not agent metadata".
- :210 `MAX_ENTRIES_REQUIRED`: "`agent.memory.longTerm.maxEntries` is
required when `agent.memory.longTerm.enabled` is true".
- :217 `REFLECTION_INTERVAL_REQUIRED`:
"`agent.memory.reflectionInterval` is required when
`agent.memory.longTerm.enabled` is true".
- :224 `REFLECTION_INTERVAL_WITHOUT_LONG_TERM`:
"`agent.memory.reflectionInterval` requires
`agent.memory.longTerm.enabled: true`".
- :242–259 `checkAgentMemoryContract`, the refinement on `memory` that
issues those three.
- PR #21413's commit 22c2d6f is an ancestor of `origin/main` (`git
merge-base --is-ancestor`, exit 0) and of the Version PR's base
36ad321 (REST compare: ahead 112, behind 0).

## Readings

- Branch cut at `origin/main` 15fe567 (the dispatch read 0c50b5d; the
one commit between touches `packages/spec/src` only, and the skill file
is byte-identical across the two).
- Changed file, whole file: 418 → 421 lines (net +3; budget ≤ +3).
- Whole package (every `skills/**/SKILL.md` summed): 4397 → 4400 lines.
- Token ratchet `node scripts/check-skills-token-ratchet.mjs`:
`skills/objectstack-ai/SKILL.md` 5486 → 5539 tokens, ceiling 6806
unchanged, headroom 1320 → 1267. Self-test: 65 cases pass.

## Verification (all at f85f008, the only commit on the branch)

Gate list derived in the worktree with `node
scripts/pm/dispatch-gates.mjs --commands` (no paths; change set off
merge base 15fe567): 24 commands, identical to the dispatch's list.
Every one exited 0; `--ran` reconciliation with exit codes recorded: "24
derived, 24 run, 0 NOT-MEASURED, 0 UNRUN … a DERIVED zero — all 24
recorded an exit code and none of them is 3".

- `pnpm --filter @objectstack/spec build` under
`scripts/pm/os-verify-lock.sh` — "VERDICT command-exit 0" (held 127s,
waited 134s), before `check:skill-docs` — "✅ Skill docs in sync".
- `check:doc-formula-expressions` first answered exit 3 (PREREQUISITE
NOT MET: `@objectstack/formula` / `@objectstack/lint` unbuilt — nothing
measured); after `turbo run build --filter=@objectstack/formula
--filter=@objectstack/lint` under the lock (VERDICT command-exit 0) it
reads "✓ check:doc-formula-expressions: 22 record-scoped formula
example(s) across 460 files / 1381 TS blocks judged clean".
- `check:skill-identifier-liveness` — "OK — Leg 1: 457 citation(s) over
53 published file(s) checked against 118371 implementation word tokens
(0 ledgered exemption(s)); Leg 2: 8 registered exhaustive section(s), 0
ledgered gap(s)".
- `check:doc-authoring` — "17369 customer-facing string(s) across 1256
spec sources clean — no internal issue-id references".
- `check:nul-bytes` — "OK (scanned 10022 text file(s) … no raw ASCII
control bytes)"; control-character grep over the edited file: 0 hits.
- `check:skill-compatibility` — "10 SKILL.md file(s) reconciled against
80 workspace packages"; `check:corpus-claim-drift`, `check:role-word`,
`check:closing-keyword-parity` (+ self-test, 40 assertions),
`check-doc-route-spelling --advisory` (+ self-test),
`check:comment-mask-corpus` (8119 files, 0 disagree),
`check:ci-filter-parity`, `check:agent-test-spelling`,
`check:cross-package-test-inputs`, `check:driver-memory-census`,
`check:gitlink-declared`, `check:pm-governed-merges`,
`check:refd-timer-probe`, `check:skill-frame-sync`,
`check:watch-hint-literal` — all green.

Changeset: none — `skills/**` is not shipped by any workspace package's
`files[]`; `skip-changeset` is requested on this PR.

## 维护者速读(草稿)

**改了什么。** 只改 `skills/objectstack-ai/SKILL.md` 的 Common Pitfalls 第 1 条里关于
`memory` 的那半句:原文说「`memory` 只是声明、没有运行时读它」,现在改成「`memory` 由 AI 运行时 ☁️ 强制执行
—— 长期记忆会被回忆与反思;`longTerm.enabled` 为 true 时 `maxEntries` 与
`reflectionInterval` 必填;存储后端不可选」,并保留「这些都不是 gate」的要点。其余一字未动。净增 3 行(预算 ≤
3),token 读数 5486 → 5539(上限 6806 未动)。

**为什么改。** 这份 skill 随 `npx skills add` 发到客户项目,AI 作者照它写元数据。spec 的
`agent.memory` 契约已经在 `main` 上落地(PR #21413),开着的 Version Packages PR
会把它随下一版一起发出去;若 skill 仍说「没有运行时读它」,AI 作者会漏写必填的 `maxEntries` /
`reflectionInterval`,或继续写已退役的 `longTerm.store`,发布时被拒。写给 AI
的文档说错一句等于产品缺陷,且必须与契约同版发运,这是 p1 的由来。

**风险与代价(含回滚)。** 纯文档改动,不发运任何包,无 changeset;本地 24 个派生门禁全绿。风险仅在措辞:三件事实均逐条对照
`packages/spec/src/ai/agent.zod.ts` 的拒收文案核过。回滚 = revert 这一个
commit(f85f008),无其它依赖。

**席位意见。** (留空,由席位定稿)

**你要做的。** 这是 Tier H 受管面(`skills/**`),需要你一次授权的 APPROVED
review;之后由席位落地。不需要你操作 Version Packages PR。

## Acceptance notes

- Out-of-scope findings: none. The `knowledge` adapter id `'memory'` at
:218–247 of the same file is unrelated to `agent.memory` and was not
touched.
- The Version Packages PR (#21352) head moved since the dispatch's
reading (f872ccf → 015a5e3); its base 36ad321 still carries
22c2d6f (REST compare: ahead 112, behind 0). The Version PR and all
changeset files are untouched by this PR.
- Governed surface (Tier H): this PR stays draft; landing waits for an
authorized approval and then the owning seat. Not flipped to ready, no
auto-merge armed.
- Writes spent by this run: `git push` (2: the empty branch probe, then
f85f008), one `pr_create` through the fleet-write relay, one
`label-write` (`skip-changeset` + assignee), one report comment. No MCP
calls.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01CB6W87z22K2yjUCDyVrJRk)_

Co-authored-by: objectstack-fleet[bot] <objectstack-fleet[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

skills/objectstack-ai/SKILL.md

@@ -309,8 +309,11 @@ there is **no top-level `temperature` / `maxTokens`** on an agent
 
 1. **Mistaking `guardrails` for a gate.** `guardrails` is enforced per user turn
    by the AI runtime ☁️ — token and time limits, blocked tool names and categories
-   refused — but it is a limit, not an approval; `memory` is declared only — no
-   runtime reads it. For a gate that is **enforced**, use
+   refused — but it is a limit, not an approval; `memory` is enforced by the AI
+   runtime ☁️ too — long-term notes are recalled and reflected on, `maxEntries`
+   and `reflectionInterval` are required once `longTerm.enabled` is true, and
+   there is no storage backend to choose — and neither is a gate. For a gate
+   that is **enforced**, use
    `enableActionApproval: true` (approval queue ☁️), `ai.requiresConfirmation` on
    the **action**, or `approval: 'always'` on an MCP tool binding. AI metadata
    edits are already gated: they land as drafts a human must publish (ADR-0033).