Skills optimization flight — skills/objectstack-ai: RESTRUCTURE (≈ −2,300 tok, −29%) — 26% of the file teaches the agent surface it forbids its readers, the flagship `defineSkill` example declares four tools that resolve to nothing, and the open-edition MCP path (the only AI path without a cloud licence) is taught nowhere

[os-litant]

Member card of the skills catalog optimization program #14292 (maintainer mandate 2026-09-02, verbatim: 「审核所有的 skills，进行全面的优化。」). Filed by the skills lane seat (session session_01LraLgQVGq8egUwfYZpbYt1). Read-only audit at objectstack origin/main a59f78d. Full findings table = audit record: the dev posts audit/objectstack-ai/findings.md (seat scratchpad) verbatim as the first comment at claim time.

Audit summary

SKILL.md 592 lines / 6,791 tok (headroom 15) · evals/README.md 315 (headroom 0) · generated _index.md 819 — package 7,925. Real usage: zero *.skill.ts / *.tool.ts / *.agent.ts files in examples or apps; only 3 patterns have real usage — action.ai.exposed + ai.description (7 usages), the MCP action bridge (examples/app-todo/test/mcp-actions.e2e.ts + all of packages/mcp), and app.defaultAgent (1). Model registry, conversations, MCPServerRef/MCPToolBinding have zero consumers outside packages/spec. The "agents are platform-internal" boundary still holds (os g agent retired with a prescription; agent.tools/agent.knowledge are retiredKey() tombstones) — yet the package spends 1,777 tokens (26%) teaching that closed surface. Verdict RESTRUCTURE: weight inverted against usage; defineTool (0 usages, no runtime reader until ADR-0109 lands) gets a full section while action.ai (7 usages) gets 371 tokens near the bottom; the description promises three surfaces the body never teaches.

Top findings

id	span	proposal	Δtok
AI-B-02	SKILL.md:145-215	DELETE agent Required/Optional/Example (section opens "third parties do not author agents"); keep 2 retirement rows	−600
AI-C-01	:28-36,83-86,89-90,126-131,330-335,339-342,360,364-365	MERGE-INTO :28-36 — "runtime is cloud/EE, open = MCP" restated 8× = 715 tok; replace 7 with a marker	−350
AI-F-04	:289-335,552-565	*.tool.ts → a note row; ADR-0109: "no runtime reader until that lands" (stack.zod.ts:594-601)	−230
AI-D-03	:495-521	DELETE §Structured Output — agent-only field the file itself calls "declared only"	−217
AI-H-01	evals/README.md:1-44	planned-eval stub, lists 5 files that don't exist (DEFERRED, #14296 item 2)	−195
AI-D-07	:362-381	REWRITE-AS-CONSTRUCT — HITL narration; every symbol cloud-closed	−165
AI-D-05	:442-456	MERGE-INTO :409-413 table — 5 items restating keys from 30 lines above	−150
AI-A-02	:475-491	REWRITE-AS-CONSTRUCT — "Model Selection"/"Temperature" taste tables; the enforced fact (temperature min 0 max 2, agent.zod.ts:38) is missing	−140
AI-B-01	:40-50	DELETE "When to Use"	−125
AI-D-01	:63-73	DELETE "Why Three Tiers?" analogy table + a false best-practice blockquote	−124
AI-D-04	:461-473	DELETE vendor model catalogue; keep the enum blockquote	−110
AI-D-06	:526-529,541-544	DELETE pitfalls 1/2/4 — generic prompt advice the frontmatter disclaims	−99
AI-C-02	:138-141	DELETE ops callout — ai_usage_daily has no open-repo object	−62
AI-E-01	:251-275	REWRITE — the flagship defineSkill example declares tools: ['query_support_case', …]; none is in PLATFORM_PROVIDED_TOOL_NAMES or stack.tools[] or action_* — exactly the failure ai-skill-tool-unresolved (packages/lint/src/validate-ai-tool-references.ts:150-171) exists to catch; the package's own defineTool example defines create_case, so the two examples don't compose	0
AI-B-03	:20-218	reorder — first customer-authorable section starts at line 218	0

Net ≈ −2,303 of 7,925 (29%) after +312 of paid additions.

Incidental falsehoods (fix in this flight)

1. SKILL.md:71-73 — "Direct tool assignment to agents is supported but considered legacy." FALSE: agent.tools is a retiredKey() tombstone → parse error (agent.zod.ts:234-236); the same file says so at :168. HIGH.
2. SKILL.md:579-580 — "any CEL predicate (e.g. a tool's availability condition)". FALSE: ToolSchema carries no CEL expression (tool.zod.ts:132-168); the only AI CEL carriers are ai/model-registry promptTemplate.system/.user. The same wrong premise sits in skills/README.md:104-105 ("AI tool params") — record it under "follow-up for skills/README.md". HIGH.
3. Residue (code fact, not a doc edit): SKILL.md:96-98 says metadata_assistant is "not vocabulary" while packages/platform-objects/src/apps/studio.app.ts:50 pins defaultAgent: 'metadata_assistant' — file as an out-of-scope card.

Three funded additions

1. Open-edition MCP wiring (+180, paid by AI-D-03): MCPServerPlugin / MCPServerRuntime from @objectstack/mcp, the /api/v1/mcp endpoint, the tool names a client sees (list_actions, run_action, query_records, describe_object).
2. skill.tools[] resolution ladder + the platform tool registry (+0, paid by AI-B-02): the ADR-0109 default path and the ~30 real names in packages/spec/src/system/constants/platform-tool-names.ts:38-80.
3. Trigger-condition operator↔value shape column (+30, paid by AI-D-01 + AI-B-01): in/not_in → array, eq/neq → string, contains → either (skill.zod.ts:37-50,130-175).

Flight scope

IMPLEMENT (same-file, shrink-only): all rows above and in the findings file at HIGH or MED; the three funded additions; falsehoods 1–2; AI-E-01 rewrite so the flagship example resolves; AI-A-01 description edit (stop promising conversations / model registry / MCP integrations the body does not teach, or teach MCP via addition 1).

ANCHOR RULINGS: MCP server / plugin wiring → this package teaches the open-edition path; objectstack-platform keeps plugin mechanics. Formula/CEL → objectstack-formula (delete the false CEL claim).

DEFER: AI-H-01 (eval stub, #14296 item 2); AI-B-04 (generator map vs body mismatch — out-of-scope card for the spec lane's build-skill-references.ts SKILL_MAP).

Flight constraints (binding)

• ONE draft PR, first line Fixes #<this card>; governed ⇒ stays draft; review requests are the seat's step.
• Token ratchet: no ratcheted file may grow; additions paid by deletions in the SAME file; ⛔ re-wrap is not payment; ⛔ no ceiling raise; ⛔ no new files; ⛔ do not touch the ratchet script.
• ⛔ Never edit another package's files or skills/README.md prose; follow-ups go in the PR body. Generated files untouched. Regenerate the README index only if a drift gate requires it (report which).
• Live surface with zero measured usage ⇒ one row pointing at its schema; retired/tombstoned ⇒ delete. A false claim matching a spec .describe() string ⇒ spec-side twin card.
• Gates: node scripts/check-skills-token-ratchet.mjs, pnpm --filter @objectstack/spec check:skill-examples, pnpm check:skill-compatibility, pnpm check:skill-identifier-liveness, plus node scripts/pm/dispatch-gates.mjs --commands <changed paths>; record the head sha.
• PR body: per-item 落点 | before | after keyed by finding id; per-file token delta; needs:contract-review on both carriers (falsehood 1 and the trigger-operator column are contract-semantics claims).

Refs: #14292 · #14296 · #13658.

[os-litant]

Claim: PM loop round 2
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14305-skills-ai-optimization
Worktree: objectstack-issue-14305
Domain: domain:skills
File surface: skills/objectstack-ai/SKILL.md ONLY (shrink-only; ceiling 6,806, headroom 15); evals/README.md untouched (AI-H-01 deferred, #14296 item 2); generated references/_index.md untouched; no file deleted ⇒ ⛔ no edit to scripts/check-skills-token-ratchet.mjs; skills/README.md + content/docs/ai/skills-reference.mdx regenerated only because the drift gate demands it after the AI-A-01 description edit (⛔ no hand edit to README prose — the false "AI tool params" CEL premise at skills/README.md:104-105 goes in the PR body as a follow-up); ⛔ no other package (stop on breach; explain in the report)
Container & model: S/M (one 6,791-token file, 592 lines; three funded additions with source-pinned semantics), mode:subagent, model: opus — --tier reads no path-derived mandate (floor sonnet · default opus · ceiling fable); the content limb applies, compensated by the seat's in-seat review at CONTRACT_REVIEW_TIER (served model read claude-fable-5-1 at 06:08Z)
Clause-②: yes — falsehood 1 (agent.tools is a retiredKey() tombstone, not "legacy"), falsehood 2 (no CEL carrier on ToolSchema), the trigger-condition operator ↔ value-shape column, the temperature bounds, the MCP tool names a client sees, and the skill.tools[] resolution ladder are contract-semantics claims ⇒ needs:contract-review on both carriers at PR creation; in-seat review before any human review request
Serial constraints cleared: this package is the ANCHOR for the open-edition MCP path (objectstack-platform keeps plugin mechanics; its delivered flight PR #14351 lists mcp → @objectstack/mcp in the requires: table and does not teach the endpoint); CEL → objectstack-formula (flight not dispatched; stable path); no open PR touches skills/objectstack-ai/**; skills/objectstack-ai/** byte-identical between a59f78d and origin/main d16df741 (seat-measured 07:1xZ); in flight alongside #14302 (query) and #14304 (api) on disjoint directories, with #14300 (pm-dispatch) delivered and under seat review

Decision re-read: no maintainer ruling on this card; binding inputs = the mandate, the value gate, the ratchet discipline, and #14296 (item 2 deferred: eval stub untouched). Falsehood 3 (metadata_assistant pinned by studio.app.ts:50) and AI-B-04 (generator SKILL_MAP mismatch) go out as out-of-scope finding cards, not doc edits. Landing form: first line Part of #14305 (the deferred eval stub keeps the card open).

---

Generated by Claude Code

[os-litant]

Claim (dev): os-dev subagent, dispatched by the skills-lane PM seat.
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14305-skills-ai-optimization (empty branch pushed as the write-route probe before any edit)
Worktree: ../objectstack-issue-14305, base d16df741808edbe39e0b6e09c993e440bad78444 (origin/main)
Assignee untouched (PM owns it).

Verified before the first edit: git diff --stat a59f78d..d16df741 -- skills/objectstack-ai/ is empty — the audit's spans are byte-identical at my base, so file:line citations resolve as written. PM mechanism assumption 1: confirmed.

Channel note: repo-scoped REST is 403 for this seat (GitHub access is not enabled for this session), so card + comment reads went through the public-repo page payload (zero quota) and writes go through MCP. git push is green.

File surface for this flight: skills/objectstack-ai/SKILL.md only, plus skills/README.md and content/docs/ai/skills-reference.mdx as generator output of check:skill-docs after the AI-A-01 description edit. evals/README.md, references/_index.md and scripts/check-skills-token-ratchet.mjs untouched.

Landing form: draft PR, first line Part of #14305 (AI-H-01 deferred to #14296 item 2 ⇒ this card stays open), needs:contract-review on both carriers.

Next comment is the full audit record, posted verbatim.

---

Generated by Claude Code

[os-litant]

audit-record — skills/objectstack-ai (read-only audit at a59f78d)

Transliteration key — the GitHub body sanitizer is measured to eat angle-bracket-shaped
fragments, so the 4 that appear in this record are spelled without angle brackets. Read:

• AI_DAILY_USER_MESSAGES=N = the env var assigned an angle-bracketed placeholder N (AI-C-02).
• action_NAME = the action_ prefix followed by an angle-bracketed name placeholder — the third
  rung of the tool-resolution ladder (AI-E-01, AI-F-04; 2 occurrences).
• os:check-marker-comment = the fence marker itself: an HTML comment whose body is os:check,
  placed directly above a fenced block (AI-E-02).

Everything else below is the audit file verbatim.

---

Audit — skills/objectstack-ai/ (published package)

Read-only audit. Pinned ref requested: objectstack origin/main = a59f78d.
Checkout note: /home/user/objectstack HEAD is a39b02a (2 commits ahead of
a59f78d). git diff --stat a59f78d..a39b02a -- skills/ is empty, so every
span below is identical at the pinned ref. Spans cited as file:line-line.

Package inventory (measured — node scripts/check-skills-token-ratchet.mjs)

File	Lines	Tokens	Ceiling / headroom
skills/objectstack-ai/SKILL.md	592	6,791	6,806 / 15
skills/objectstack-ai/evals/README.md	44	315	315 / 0
skills/objectstack-ai/references/_index.md	45	819	generator-owned, not ratcheted
Package total	681	7,925	—

Sibling sizes for scale: data 13,892 · platform 12,984 · automation 12,768 ·
pm-dispatch 14,549 · i18n 6,337 · api 6,311 · formula 6,002 · query 5,443.

Real-usage census (what I grepped)

Grepped examples/**, packages/apps/**, packages/** (excluding
node_modules, .git) for every surface the package teaches:

Surface taught	Real usages found	Where
action.ai.exposed + ai.description	7	examples/app-todo/src/actions/task.actions.ts:16,33,109,126,148,168; examples/app-showcase/src/ui/actions/index.ts:431
MCP server runtime (@objectstack/mcp)	1 e2e + whole package	examples/app-todo/test/mcp-actions.e2e.ts:22,110-113; packages/mcp/src/** (30 files)
app.defaultAgent	1	packages/platform-objects/src/apps/studio.app.ts:50
*.skill.ts / defineSkill	0 authored	CLI template exists: packages/cli/src/commands/generate.ts:184-251
*.tool.ts / defineTool	0 authored	ADR-0109: stack.tools "has no runtime reader until that lands" (packages/spec/src/stack.zod.ts:594-601)
*.agent.ts / defineAgent	0 third-party	os g agent is retired: packages/cli/src/commands/generate.ts:301-319
KnowledgeSource registration	0 in examples	Impl real: packages/services/service-knowledge, packages/plugins/knowledge-{memory,ragflow}, packages/plugins/embedder-openai
Model registry entries	0 consumers outside packages/spec	grep -rl ModelRegistryEntry|ModelRegistrySchema packages/ examples/ → only packages/spec/**
Conversations	0 consumers outside packages/spec	same grep for ConversationSchema
MCPServerRef / MCPToolBinding	0 consumers outside packages/spec	same grep

find examples packages/apps -name "*.skill.ts" -o -name "*.tool.ts" -o -name "*.agent.ts" → zero files.

Distinct real-usage patterns: 3 (action.ai exposure · MCP action bridge ·
app.defaultAgent). Everything else the package teaches is a supported-but-unused
surface, a cloud-closed surface, or a zero-consumer schema.

---

Findings

id	dim	file:span	evidence	proposal	Δtok	value gate ①②③	conf	human-floor
AI-A-01	A	skills/objectstack-ai/SKILL.md:3-10	Description promises "AI skills, tools, knowledge sources, conversations, model registry entries, and MCP integrations". Body coverage: grep -ni conversation SKILL.md → only the word "Conversational" at :80,489; model registry → one parenthetical at :470-473; MCP → four edition-boundary asides (:28,35,86,130,342,535), no authoring content. Three of six advertised surfaces are untaught, and all three have zero consumers outside packages/spec (census above).	REWRITE-AS-CONSTRUCT — cut conversations, model registry entries, and MCP integrations from the description; add MCP back only alongside AI-F-01's addition	−18	① yes — stops a customer agent loading this package for conversation/model-registry work it cannot help with ② yes, deletion is the whole fix ③ n/a (frontmatter)	HIGH	yes
AI-A-02	A	skills/objectstack-ai/SKILL.md:9-10 vs :475-491	Description: "Do not use for general LLM prompting questions unrelated to ObjectStack metadata." Body then spends 163 tokens on "Model Selection Guidelines" (GPT-4o / Claude Sonnet 4 for "complex reasoning") and "Temperature Guidelines" (0.7–1.0 Creative writing) — vendor-catalogue advice with no ObjectStack decision in it. The enforced fact is absent: temperature: z.number().min(0).max(2) (packages/spec/src/ai/agent.zod.ts:38) — a parse error outside 0–2.	REWRITE-AS-CONSTRUCT — delete both tables, keep one line: `model`: free string · `temperature` 0–2 (parse error outside) · `maxTokens`/`topP` optional	−140	① yes — the 0–2 bound changes what parses; "GPT-4o for reasoning" changes nothing ② yes ③ yes — one line replaces two taste tables	HIGH	no
AI-B-01	B	skills/objectstack-ai/SKILL.md:40-50	"## When to Use This Skill" is a 5-bullet restatement of the frontmatter description the agent has already read (both say: skills, tools, knowledge sources for RAG, LLM models, agents are read-only).	DELETE	−125	① no decision changes ② deletion is the fix ③ n/a	HIGH	no
AI-B-02	B	skills/objectstack-ai/SKILL.md:145-215	792 tokens of AgentSchema reference (Required Properties, 12-row Optional Properties, a 34-line defineAgent example) opening with its own disclaimer: "Reference only — third parties do not author agents." The runtime agrees: packages/cli/src/commands/generate.ts:301-319 retires os g agent; packages/lint/src/validate-ai-agent-authoring.ts:8-14 — "listAgents() filters non-platform records out of the catalog, and loadAgent() refuses them outright … a stack-authored agent 404s on chat". Zero *.agent.ts in the repo.	DELETE §Required/Optional/Example; keep ~80 tokens: the two retired-key rows (:168 agent.tools, :171 agent.knowledge) folded into the existing :96-101 callout, and a pointer to references/_index.md for AgentSchema	−600	① the deleted text changes no decision a third party may legally make ② yes ③ yes — 2 retirement lines survive as the construct	HIGH	yes
AI-B-03	B	skills/objectstack-ai/SKILL.md:20-218	Section order: the first authorable-by-a-customer surface (## Skill Configuration) begins at line 218 — 199 lines (≈33% of the file) of preamble: three-tier diagram, "Why Three Tiers?" analogy, built-in-agent narration, and the reference-only agent section. The two surfaces with actual repo usage (action.ai at :337, MCP at nowhere) sit at the bottom or are absent.	MOVE-TO — reorder: Skill Configuration → Actions-as-tools → MCP (new) → Knowledge → Tool metadata (with its ADR-0109 "usually don't author this" caveat) → agent/edition reference	0	① yes — the first 1,500 tokens an agent reads should be the task it was loaded for ② partly (AI-B-02 removes most of the preamble) ③ n/a	HIGH	yes
AI-B-04	B	skills/objectstack-ai/references/_index.md:12-21 vs SKILL.md body	The generated index advertises 10 core schemas; the body teaches 4 (agent, tool, skill, knowledge-source). conversation.zod.ts, mcp.zod.ts, embedding.zod.ts, knowledge-document.zod.ts, usage.zod.ts are listed but never mentioned. Conversely ai/solution-blueprint.zod.ts — the schema behind the solution_design skill the body names at :120 — is absent from the generator map (packages/spec/scripts/build-skill-references.ts:98-109).	(generator-owned; no direct edit) FLAG — a maintainer ruling: either the map narrows to what the body teaches, or the body earns the extra schemas. Record as the input to AI-A-01.	0	① yes — an index promising 6 untaught schemas invites the agent to Read node_modules it has no guidance for ② n/a ③ n/a	MED	yes
AI-C-01	C	skills/objectstack-ai/SKILL.md:28-36, 83-86, 89-90, 126-131, 330-335, 339-342, 360, 364-365	The single fact "the in-product AI runtime is cloud/EE; the open edition is MCP-only" is restated 8 times, measured at 183+65+43+115+107+74+94+34 = 715 tokens. Sample duplication — :28-31 "The in-UI AI runtime … ships in the cloud / Enterprise distribution, not the open framework" vs :126-128 "All four are cloud-runtime skills — none resolves on OSS. The open framework ships no in-product agent (there is no service-ai package)" vs :339-342 "Cloud / EE runtime. registerActionsAsTools(), AIServicePlugin, and the HITL approval queue below ship in @objectstack/service-ai".	MERGE-INTO :28-36 (the canonical anchor — it is the file's first blockquote and names the package). Replace the other seven with a bare ☁️ marker on the affected headings, defined once in the anchor.	−350	① no — restatements 2–8 change no decision the anchor has not already changed ② yes ③ yes — one legend + 7 glyphs	HIGH	no
AI-C-02	C	skills/objectstack-ai/SKILL.md:138-141	"Ops: set AI_DAILY_USER_MESSAGES=N … (backed by the ai_usage_daily object …). Adapter health is observable at GET /api/v1/ai/status". This is cloud-runtime operations, not metadata authoring; objectstack-platform owns ops (its ## Verify your work / CLI / deploy sections, skills/objectstack-platform/SKILL.md:1135). ai_usage_daily does not exist in the open repo (find packages/platform-objects/src -name "*ai*" → no AI objects).	DELETE (or MOVE-TO objectstack-platform if a maintainer wants it published at all)	−62	① no — an authoring agent never sets a cloud env var ② yes ③ n/a	HIGH	no
AI-D-01	D	skills/objectstack-ai/SKILL.md:63-73	"### Why Three Tiers?" — a 3-row analogy table (Agent = "Job role (e.g., 'Help Desk Agent')") plus a Best-practice blockquote. Pure rationale; the ASCII diagram at :55-61 already carries the shape. The blockquote is also false — see Incidental falsehood #1.	DELETE	−124	① no ② yes ③ the :55-61 diagram is already the construct	HIGH	no
AI-D-02	D	skills/objectstack-ai/SKILL.md:24-26	"This skill covers the Agent → Skill → Tool three-tier architecture aligned with Salesforce Agentforce, Microsoft Copilot Studio, and ServiceNow Now Assist patterns." Competitive positioning, paid in every customer session.	DELETE	−43	① no ② yes ③ n/a	HIGH	no
AI-D-03	D	skills/objectstack-ai/SKILL.md:495-521	"## Structured Output" — 217 tokens teaching structuredOutput (format, strict, maxRetries, fallbackFormat, transformPipeline). It is an agent-only field (declared in packages/spec/src/ai/agent.zod.ts — StructuredOutputConfigSchema, no other carrier), i.e. a surface the same file forbids third parties at :147-152; and the same file says at :173 and :530-532 that it is "declared only — no runtime reads them". A section on an unreadable field of an unauthorable type.	DELETE	−217	① no decision an app author may make ② yes ③ n/a	HIGH	yes
AI-D-04	D	skills/objectstack-ai/SKILL.md:461-473	"### Supported Providers" — 4-row table of vendor model catalogues ("GPT-4o, GPT-4o-mini, o1, o3-mini", "Ollama, vLLM, llama.cpp"). The decision-changing content is the two enums, already in the blockquote at :470-473: AIModelConfigSchema.provider = openai|azure_openai|anthropic|local (packages/spec/src/ai/agent.zod.ts:36) and ModelProviderSchema adds google|cohere|huggingface|custom (packages/spec/src/ai/model-registry.zod.ts:17-26).	DELETE the table, keep the blockquote	−110	① no — model names date and change no parse outcome ② yes ③ yes, the enum blockquote survives	HIGH	no
AI-D-05	D	skills/objectstack-ai/SKILL.md:442-456	"### Knowledge Source Best Practices" — 5 numbered items restating the property table 30 lines above: item 1 where ← :411; item 2 contentFields ← :411; item 3 metadataFields ← :411; item 4 aiExposed ← :405; item 5 (adapter-side tuning) repeats the callout at :436-440 verbatim in substance.	MERGE-INTO the :409-413 source-kinds table (one "guidance" column)	−150	① no new decision ② yes ③ yes — a column replaces 5 paragraphs	HIGH	no
AI-D-06	D	skills/objectstack-ai/SKILL.md:526-529, 541-544	Pitfalls 1, 2, 4, 5 are generic prompt-engineering advice — "Overly broad instructions. Agents with vague instructions hallucinate more"; "Too many tools per skill … (3–8 tools)"; "The LLM uses tool description to decide when to call it". Nothing ObjectStack-specific; contradicts the frontmatter's own "Do not use for general LLM prompting questions". Pitfall 5's real content (no phrase matching) is already the triggerPhrases tombstone story and is stated at :543-544 only in the negative.	DELETE 1, 2, 4; keep 5 folded into the trigger-conditions construct (AI-F-03)	−99	① no ② yes ③ yes	HIGH	no
AI-D-07	D	skills/objectstack-ai/SKILL.md:362-381	"### Human-In-The-Loop approval" — 255 tokens (plugin snippet, 4-step flow narration, 4 IAIService method names). Every symbol is cloud-closed: grep -rl AIServicePlugin|proposePendingAction packages/ examples/ finds no open implementation (only packages/spec/src/contracts/ai-service.ts type declarations and CHANGELOGs). No open-edition customer can run any of it.	REWRITE-AS-CONSTRUCT — 3 lines: enableActionApproval: true gates mode:'delete'/variant:'danger'/ai.requiresConfirmation actions through ai_pending_actions; triage in Studio; cloud-only	−165	① the flow narration changes no authoring decision — only "does my action get held?" does, and that is the :354-356 skip table ② yes ③ yes	MED	yes
AI-E-01	E	skills/objectstack-ai/SKILL.md:251-275	The flagship Skill Example teaches the exact failure mode the platform's own lint rule exists to catch. It declares tools: ['query_support_case','create_support_case','update_support_case','escalate_case']. The resolution ladder is stack.tools[].name ∪ PLATFORM_PROVIDED_TOOL_NAMES ∪ action_NAME (packages/lint/src/validate-ai-tool-references.ts:150-171); none of the four is in the registry (packages/spec/src/system/constants/platform-tool-names.ts:38-80) and none is action_*, so all four raise ai-skill-tool-unresolved (warning) unless the app also ships four stack.tools records the example never shows. The rule's own docblock names this: "the HotCRM failure — 10 fictional tools across 6 skills … a copilot that claims abilities it does not have" (validate-ai-tool-references.ts:28-31). The package's defineTool example one section later defines create_case, not create_support_case — the two examples do not even compose.	REWRITE-AS-CONSTRUCT — rewrite the example on the ADR-0109 default path: tools: ['action_escalate_case', 'query_records', 'get_record'] with a one-line comment naming the ladder	+0 (in-place)	① yes — this is the single highest-consequence decision the package changes ② no, a rewrite ③ yes	HIGH	yes
AI-E-02	E	skills/objectstack-ai/SKILL.md:367-372, 499-514	Fence-marker audit per packages/spec/scripts/check-skill-examples.ts:14-23 (os:check-marker-comment directly above the fence). 6 TypeScript fences: 4 marked (:185, :251, :305, :418), 2 unmarked (:367 kernel.use(new AIServicePlugin({…})), :499 a bare structuredOutput: {…} literal). Both are legitimately unmarked — :499 is a fragment in statement position (TS1109, trap 1 in the script's header) and :367 imports nothing; but AIServicePlugin is exported by no open package (grep -rn "export class AIServicePlugin" → nothing), so it could never be marked.	No gate defect. :499 disappears under AI-D-03; :367 shrinks under AI-D-07.	0	① n/a ② n/a ③ n/a	HIGH	no
AI-F-01	F	package-wide (absence)	The one AI path that actually executes in the open edition has zero coverage. grep -rn "MCPServerRuntime|MCPServerPlugin|list_actions|run_action|/api/v1/mcp" skills/ → 0 hits across all 11 published packages. Yet examples/app-todo/test/mcp-actions.e2e.ts boots exactly that path (:18-24 ObjectKernel + ObjectQLPlugin + DriverPlugin + AppPlugin + MCPServerRuntime) and asserts the tool names a customer's client will see (:110-113 list_actions, run_action, query_records). packages/mcp/src/index.ts:13-17 exports MCPServerPlugin, MCPServerRuntime, registerObjectTools, registerActionTools. The package tells the reader six times to "expose the app to your own AI via @objectstack/mcp (BYO-AI)" and never once shows how.	ADD — a ~180-token construct: kernel.use(new MCPServerPlugin()), the endpoint /api/v1/mcp, and the tool names an MCP client gets (list_actions, run_action, query_records, describe_object). Paid by AI-D-03 (−217), same file.	+180 / net −37	① yes — it is the difference between a working open-edition AI story and none ② no, this is the one place addition beats deletion ③ yes — a wiring snippet + tool-name list	HIGH	yes
AI-F-02	F	skills/objectstack-ai/SKILL.md:386-391, 560 (absence)	RAG wiring is unreachable from the package. It says sources are "registered at runtime via IKnowledgeService.registerSource()" and never names the package that provides it. grep -n "service-knowledge|KnowledgeServicePlugin|knowledge-memory|knowledge-ragflow|embedder-openai" skills/objectstack-ai/SKILL.md → 0 hits (and 0 in objectstack-platform). The real, copy-pasteable shape is KnowledgeServicePlugin({ sources: [...] }) (packages/services/service-knowledge/src/knowledge-service-plugin.ts:17-32, 119-121), plus an adapter plugin (KnowledgeMemoryPlugin / KnowledgeRagflowPlugin, packages/plugins/knowledge-{memory,ragflow}/src/index.ts:207 / :277). The adapter: 'memory' / 'ragflow' ids at :399,424 are unresolvable without them.	ADD — 4 lines naming @objectstack/service-knowledge + KnowledgeServicePlugin({ sources }) + the two adapter packages, appended to the existing example at :417-434. Paid by AI-D-05 (−150), same file.	+90 / net −60	① yes — without a package name the example cannot be wired at all ② no ③ yes	HIGH	yes
AI-F-03	F	skills/objectstack-ai/SKILL.md:277-286 (gap)	The "### Trigger Conditions" table lists the 5 operators and nothing else. Since #7113 the schema refuses a mismatched value shape: in/not_in require an array, eq/neq require a string, contains accepts either (packages/spec/src/ai/skill.zod.ts:37-50, 130-175, 195-202 — superRefine(checkSkillTriggerConditionValueShape)). Writing { operator: 'in', value: 'admin' } is a parse error the package gives no warning about.	ADD one column to the existing table (value shape per operator). Paid by AI-D-01 (−124) + AI-B-01 (−125), same file.	+30 / net −219	① yes — turns a parse failure into a correct first draft ② no ③ yes — a column on a table that already exists	HIGH	no
AI-F-04	F	skills/objectstack-ai/SKILL.md:289-335, 552-565	The package gives *.tool.ts a full section plus a blueprint row (:559 "Tool metadata	src/tools/query-leads.tool.ts") — a surface with zero repo usages and, per ADR-0109, no reader: "stack.tools record exists only for AI-presentation refinement (Phase 2 …) and has no runtime reader until that lands" and "the DEFAULT third-party path declares no tool records at all" (packages/spec/src/stack.zod.ts:594-601; packages/spec/src/system/constants/platform-tool-names.ts:21-26). SKILL.md states the weaker "read-only projection … not an execution entry point" (:330-335) but never states don't author one by default, and its blueprint table still presents it as a standard layer.	RETIRE-SURFACE (demote) — cut §Tool Configuration to a ~120-token note ("default path: name platform tools / action_NAME; author a tool record only for AI-presentation refinement — no runtime reader yet") and drop the blueprint row	−230	① yes — reverses the default the reader takes away ② yes ③ yes	MED
AI-G-01	G	skills/objectstack-ai/SKILL.md:71-73 vs :168	Internal contradiction, 145 lines apart. :72-73: "Direct tool assignment to agents is supported but considered legacy." :168: "tools	REMOVED in protocol 17 … A parse error now". Implementation sides with :168: tools: retiredKey('agent.toolswas removed in @objectstack/spec 17 — useskills. …') (packages/spec/src/ai/agent.zod.ts:234-236).	DELETE :71-73 (subsumed by AI-D-01)	−0 (counted in AI-D-01)	① yes — "supported" invites an author to write a key that will not parse ② yes ③ n/a	HIGH
AI-G-02	G	skills/objectstack-ai/SKILL.md:579-580	"It confirms the agent/tool/model metadata conforms to the protocol and that any CEL predicate (e.g. a tool's availability condition) parses and resolves." No such field exists: ToolSchema declares exactly name, label, description, parameters, outputSchema, objectName (packages/spec/src/ai/tool.zod.ts:132-168), and grep -n "ExpressionSchema|CelExpression" packages/spec/src/ai/*.zod.ts returns no expression carrier in the AI domain. skills/README.md:104-105 routes "AI tool params" to objectstack-formula on the same mistaken premise; skills/objectstack-formula/SKILL.md:473 lists the AI carriers correctly — ai/model-registry promptTemplate.system/.user only.	REWRITE — replace the parenthetical with (e.g. a model-registry promptTemplate); flag skills/README.md:104-105 to the same effect	−5	① yes — the example sends the agent looking for a field that does not exist ② no ③ n/a	HIGH	no
AI-G-03	G	skills/objectstack-ai/SKILL.md:297	outputSchema is presented as a peer of objectName with no caveat, but the schema marks it '[EXPERIMENTAL — not enforced] JSON Schema for tool output. Keys are folded into the tool description only; outputs are not validated.' (packages/spec/src/ai/tool.zod.ts:161). The package flags every other declared-only field (guardrails, memory, structuredOutput at :172-175, :530-532) — this one silently reads as enforced.	REWRITE — append "(experimental; folded into the description, outputs not validated)"	+12	① yes — same class of "declared-only" trap the package already guards elsewhere ② no ③ n/a	HIGH	no
AI-H-01	H	skills/objectstack-ai/evals/README.md:1-44	315 tokens, zero domain content. It is a meta-template: a "Structure" fence listing five eval files that do not exist (find skills/objectstack-ai -type f → 3 files total), a generic "Format" list, a "Contributing" checklist, and "⚠️ Not yet implemented". It tests none of the decisions the package changes. Compare skills/objectstack-data/evals/README.md — 143 tokens, same placeholder status, but names 6 concrete domain scenarios; skills/objectstack-query/evals/README.md — 558 tokens of planned evals each with an expected answer and a penalty condition.	REWRITE-AS-CONSTRUCT — replace with a data-style candidate list: trigger-condition value shape (AI-F-03), skill.tools[] resolution ladder (AI-E-01), action.ai.exposed + ≥40-char description, agent.tools/knowledge/skill.permissions retirements, knowledge where/contentFields hygiene	−195	① a placeholder that lists non-existent files changes no decision and misleads the next author ② yes ③ yes	HIGH	no
AI-H-02	H	skills/objectstack-ai/evals/README.md:13-24	The fenced directory tree is a dead reference: evals/skills/test-trigger-conditions.md, evals/tools/test-json-schema-parameters.md, evals/knowledge/test-knowledge-source-filters.md etc. — none exists. A grader or agent reading the package sees a structure that is not there.	DELETE (subsumed by AI-H-01)	−0	① yes ② yes ③ n/a	HIGH	no
AI-I-01	I	package-wide	7,925 tokens against 3 distinct real-usage patterns. 26% of SKILL.md (1,777 tokens: :75-143 built-in-agent narration 985 + :145-215 agent reference 792) is spent on a surface the package itself declares closed to its readers, while the surface with 7 real usages (action.ai) gets 371 tokens at :346-360 and the surface that actually executes on the open edition (MCP) gets 0.	(composite of AI-B-02, AI-C-01, AI-D-03, AI-F-01)	—	—	HIGH	yes

Net (SKILL.md only)

Deletions AI-A-02 (−140), AI-B-01 (−125), AI-B-02 (−600), AI-C-01 (−350),
AI-C-02 (−62), AI-D-01 (−124), AI-D-02 (−43), AI-D-03 (−217), AI-D-04 (−110),
AI-D-05 (−150), AI-D-06 (−99), AI-D-07 (−165), AI-F-04 (−230), AI-G-02 (−5)
= −2,420; additions AI-F-01 (+180), AI-F-02 (+90), AI-F-03 (+30),
AI-G-03 (+12) = +312. Net SKILL.md ≈ −2,108 of 6,791 (31%).
Plus evals −195 of 315. Package net ≈ −2,303 of 7,925 (29%), with the
structural reorder (AI-B-03) on top.

---

Incidental falsehoods (by-product; the 2026-08-31 sweep is not being re-run)

1. SKILL.md:71-73 — "Best practice: Always model via Skills first.
   Direct tool assignment to agents is supported but considered legacy."
   FALSE. agent.tools is a retiredKey() tombstone — authoring it is a parse
   error with the migration attached
   (packages/spec/src/ai/agent.zod.ts:234-236: "agent.tools was removed in
   @objectstack/spec 17 — use skills"). The same SKILL.md says so at :168
   ("REMOVED in protocol 17 … A parse error now"). Confidence HIGH.

2. SKILL.md:579-580 — "any CEL predicate (e.g. a tool's availability
   condition) parses and resolves". FALSE example. ToolSchema has no
   condition/expression field of any kind — name, label, description,
   parameters, outputSchema, objectName
   (packages/spec/src/ai/tool.zod.ts:132-168) — and no schema in
   packages/spec/src/ai/*.zod.ts carries a CEL expression. The only AI CEL
   carriers are ai/model-registry promptTemplate.system / .user, as
   skills/objectstack-formula/SKILL.md:473 correctly states. The same wrong
   premise sits in the catalog: skills/README.md:104-105 routes "AI tool
   params" to objectstack-formula. Confidence HIGH.

3. SKILL.md:96-98 (minor, advice-vs-platform mismatch, not a falsehood) —
   "data_chat→ask and metadata_assistant→build … are not vocabulary
   — always write ask / build." The platform's own shipped app still pins the
   legacy alias: defaultAgent: 'metadata_assistant'
   (packages/platform-objects/src/apps/studio.app.ts:50). The skill's advice is
   right for authors; recorded so the retired-spelling ledger sees the residue.
   Confidence HIGH (on the code fact).

---

Generated by Claude Code