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

[objectstack-fleet]

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 feat(spec)!: an agent's memory contract states exactly what the runtime honours — maxEntries and reflectionInterval are required once long-term memory is enabled, longTerm.store is retired, and the block is live #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 (chore: version packages #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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f85f0082976e8810b1e4ad2e7636c46736cce546
Local-runs: none

Read-only shape: the diff against the merge base 15fe567, card #21415 with every comment, and this head's check-runs; nothing built or run locally. Reviewed by the dispatch seat in seat (served tier equals the constant's value, read from get_session). Review face: skills/**, governed rule text (Tier H). Readings taken at 2026-10-04T00:16Z.

① Derived judgments

• Accept set: unchanged. One clause of prose in skills/objectstack-ai/SKILL.md (+5/−2, one file); no schema, export, error code, route or runtime behaviour moves. Clause-②: no holds; the text moves from "declared only" to "enforced", a narrowing of what an author is told is safe to omit, never a widening.
• Statements the clause adds, each checked against origin/main 15fe567, packages/spec/src/ai/agent.zod.ts: maxEntries required when longTerm.enabled is true (MAX_ENTRIES_REQUIRED, :210); reflectionInterval required then (REFLECTION_INTERVAL_REQUIRED, :217) and refused without an enabled longTerm (REFLECTION_INTERVAL_WITHOUT_LONG_TERM, :224); longTerm.store retired, storage is the platform's (LONG_TERM_STORE_RETIRED, :196); the refinement checkAgentMemoryContract (:242) wired by .superRefine (:550). The ☁️ marker is right: the enforcing runtime is cloud's AI service, as the file's header comment (:185–188) states. The pitfall's point that none of this is a gate is kept; the following sentence is untouched. git grep "declared only" on the head: 0 hits in the skill (control guardrails: 2).
• Scope: the claim's one file, the one clause; the knowledge adapter id 'memory' elsewhere in the file is a different thing and is untouched.

② Semver level

• No released package publishes from this diff; no changeset owed; skip-changeset is the correct declaration. No ADR-0087 disposition applies. Release coupling: the open Version Packages PR chore: version packages #21352 carries PR feat(spec)!: an agent's memory contract states exactly what the runtime honours — maxEntries and reflectionInterval are required once long-term memory is enabled, longTerm.store is retired, and the block is live #21413's contract, so this text ships with it — the reason for p1 — and nothing in this PR touches that PR or any changeset file.

③ Boundary flags

• Dev flags: open_questions empty; out_of_scope_findings empty; deviations none.
• Ratchet, read off the PR head blob by this seat: 418 → 421 lines (+3, the dispatch budget); 5486 → 5539 tokens (ceiling 6806); catalog SKILL.md sum 4397 → 4400. No ceiling moved.
• Check-runs on this head at this write: TypeScript Type Check success, Governed Surface Queue Guard success, Check Changeset success; Lint & Repo Gates and Test Core (1/6) in progress — the enqueue gate reads them at landing, not this record.

Implemented-by: claude/issue-21415-ai-skill-memory-enforced
Reviewed-by: session_01CB6W87z22K2yjUCDyVrJRk

VERDICT: PASS

[objectstack-fleet]

维护者速读(终稿)— PR #21652(#21415)· skills seat 1 · 2026-10-04T00:28Z

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

为什么改: agent.memory 契约已随 PR #21413 落到 main,开着的 Version Packages PR(17.7.0)会把它随下一版发出;技能若仍说「没有运行时读它」,AI 作者会漏写必填项,或继续写已退役的 longTerm.store,发布时被拒。写给 AI 的技能说错一句等于产品缺陷,须与契约同版发运,这是 p1 的由来。

风险与代价(含回滚): 纯技能文本,无 changeset(skip-changeset),不碰 Version PR 与任何 changeset 文件。席内契约复核 PASS(5974915471),必查门禁 Lint & Repo Gates 与 TypeScript Type Check 已绿。回滚 = revert 单个 commit f85f008。

席位意见: 建议批准。三件事实逐条对照 packages/spec/src/ai/agent.zod.ts 的四条拒收文案(:196、:210、:217、:224)与 :242 的 refinement 核过;☁️ 标记正确,强制者是云端 AI 运行时。

你要做的(一个动作): 在 PR #21652 上给一次 APPROVED review;批准后由席位清标、ready、挂 auto-merge 入队。