Skills optimization flight — skills/objectstack-api: RESTRUCTURE (≈ −2,125 tok, −31%) — the leading canonical example teaches `RestApiEndpointSchema` (0 consumers repo-wide), three sections are other packages' anchors, and the description forbids the client seat that ~660 tokens of body then teach

[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-api/findings.md (seat scratchpad) verbatim as the first comment at claim time.

Audit summary

SKILL.md 6,311 tok (headroom 8) · evals/README.md 546 (headroom 0) · generated _index.md 888 — 7,745 paid per customer session; 705 lines; no rules/, zero eval fixtures. Real usage: 3 api-owned patterns — declarative apis: (2), http.server code mount (3), public anonymous form (2) — plus defineDatasource (4, belongs to data). Zero usages repo-wide: *.endpoint.ts, RestApiEndpointSchema, apiMethods, ServiceInfo, projectResolution, realtime authoring, ?preview=draft/?package=. The ADR-0121 declarative-apis: block (:149-254) is excellent and implementation-faithful; ~2,400 tokens go to surfaces with zero real usage or to other packages' anchors. Fence audit: 8 TS fences, 6 marked, no rot; one marked block (:532) type-checks against a locally declared shape, not the real PluginContext. Verdict RESTRUCTURE.

Top findings

id	span	proposal	Δ
API-H-01	evals/README.md:1-49	planned-eval stub (DEFERRED, #14296 item 2)	−400
API-C-01	SKILL.md:472-510	DELETE — datasources/drivers duplicate objectstack-data/rules/datasources.md + objectstack-platform/SKILL.md:353-357 (which has the Turso EE caveat api omits)	−300
API-E-01	SKILL.md:117-146	DELETE — leading os:check example teaches RestApiEndpointSchema, 0 consumers; no plugin-rest-api package; RestApiPluginConfig has no endpoints key	−294
API-F-05	SKILL.md:316-344	ServiceInfo is a response shape, 0 usages, not in the package's own SKILL_MAP → one row	−230
API-C-02	SKILL.md:513-538	DELETE — duplicates objectstack-platform/rules/service-registry.md and fabricates the host shape at :532	−226
API-B-03	:65-71,283-313,559-563	MERGE — the apiMethods primitives/derived rule stated 3× in-file	−180
API-A-03	:8-9 vs :73-94,316-366	the description forbids the client seat; 663 tok of body teach it → delete to a pointer	−150
API-C-03	SKILL.md:458-468	DELETE — Security Layers table names no authorable key	−138
API-D-02	SKILL.md:384-396	DELETE — Handler Status table neutralised by its own callout ("nothing reads it at runtime")	−130
API-B-01	SKILL.md:419-429	DELETE — third rendering of "no nested auth block"	−120
API-D-01	SKILL.md:346-366	REWRITE-AS-CONSTRUCT → one line (health/ready are author-free)	−120
API-D-03	:544-547,:556-558	DELETE Best Practices 1 & 4	−109
API-D-04	SKILL.md:569-576	DELETE pitfalls 1/2/4 — "use FLS" has no authorable spelling; the page sizes match no platform constant	−95
API-D-05	SKILL.md:191-198	DELETE carve-out why-prose, keep the rule	−90
API-B-05	SKILL.md:22-28	DELETE preamble restating the frontmatter	−78

Net −2,125 (31%) at HIGH/MED-HIGH; −2,525 (37%) incl. MED. Incidental falsehoods: none (spot-checks held).

Three funded additions

1. http.server code-mount canonical example (+130, paid by API-E-01) — the only code-route pattern the repo ships (3 sites); needs the kernel:ready timing rule, the readServer('http.server') ?? readServer('http-server') dual lookup, and that getService is async.
2. ADR-0112 error-code ledger construct (+120, paid by API-C-02) — two-tier vocabulary; unregistered code fails parse → fails CI; a downstream repo keeps its own ledger via envelopeViolations(body) + makeApiErrorSchema(<own ledger>) (contract.zod.ts:146,215).
3. OCC contract (+40, paid by API-D-03) — If-Match header or expectedVersion body field (body wins), token typically updated_at, mismatch → 409 CONCURRENT_UPDATE (rest-server.ts:7711-7721).

Flight scope

IMPLEMENT (same-file, shrink-only): every DELETE / MERGE / REWRITE row above and in the findings file at HIGH or MED; the three funded additions; API-A-02/A-03 frontmatter edits; fix or unmark the :532 block so the gate proves something real.

ANCHOR RULINGS: datasources → objectstack-data/rules/datasources.md (delete + pointer); service registry → objectstack-platform/rules/service-registry.md and SKILL.md:353-357 (delete + pointer; the platform flight keeps those); request-side query syntax → objectstack-query.

DEFER: API-H-01 (eval stub, #14296 item 2); API-F-06 (declared-but-unenforced semantics → out-of-scope card for triage, not a doc edit).

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; a missing/weaker anchor goes in the PR body under "follow-up for ". Generated files untouched. Frontmatter edits: regenerate skills/README.md 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 (the OCC and error-ledger additions are contract-semantics claims).

Refs: #14292 · #14296 · #13658.

[os-litant]

Claim: PM loop round 2
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14304-skills-api-optimization
Worktree: objectstack-issue-14304
Domain: domain:skills
File surface: skills/objectstack-api/SKILL.md ONLY (shrink-only; ceiling 6,311, headroom 8); evals/README.md untouched (API-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 API-A-02/A-03 frontmatter edits; ⛔ no other package (stop on breach; explain in the report)
Container & model: S/M (one 6,311-token file, 705 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 — the OCC contract (If-Match / expectedVersion, 409 CONCURRENT_UPDATE), the ADR-0112 error-code ledger construct, and the http.server mount timing / dual-lookup rule are contract-semantics claims ⇒ needs:contract-review on both carriers at PR creation; in-seat review before any human review request
Serial constraints cleared: anchors are stable paths — datasources → objectstack-data/rules/datasources.md (the data flight PR #14427 left it byte-identical); service registry → objectstack-platform/rules/service-registry.md and the driver-selection table in objectstack-platform/SKILL.md (the platform flight PR #14351 kept both but moved sections — point BY HEADING, not line number; the well-known plugin-name → service-key table now lives in platform SKILL.md under "Well-Known Plugin Names & Services"); request-side query syntax → objectstack-query (flight #14302 in progress keeps the filter-DSL sections addressable — point at rules/filters.md by heading); no open PR touches skills/objectstack-api/**; in flight alongside #14302 (query) and #14300 (pm-dispatch) on disjoint directories, with #14299 (platform) and #14297 (data) 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). API-F-06 goes out as an out-of-scope finding card, not a doc edit. Landing form: first line Part of #14304 (the deferred eval stub keeps the card open).

---

Generated by Claude Code

[os-litant]

Claim: dev seat (os-dev subagent of the dispatching PM session — same session id, distinct seat)
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14304-skills-api-optimization
Worktree: ../objectstack-issue-14304 (from origin/main)

Scope taken as dispatched: edits confined to skills/objectstack-api/SKILL.md, plus skills/README.md and content/docs/ai/skills-reference.mdx only as generator output of pnpm --filter @objectstack/spec gen:skill-docs after the API-A-02/A-03 frontmatter edits. evals/README.md untouched (API-H-01 deferred to #14296 item 2); generated references/_index.md untouched; ⛔ no ceiling raise, no new files, no edit to scripts/check-skills-token-ratchet.mjs, no edit to any other package (MERGE-INTO = delete here + one-line pointer; a missing or weaker anchor is reported in the PR body under "follow-up for PACKAGE").

Landing form: ONE draft PR against main, first line Part of #14304 (⛔ not a closing keyword — API-H-01 stays deferred, so this card stays open). needs:contract-review on both the card and the PR at PR creation; skip-changeset on the PR.

Next comment on this card is the full read-only audit record (audit/objectstack-api/findings.md at a59f78d) verbatim, which is the finding-by-finding spec for this flight.

---

Generated by Claude Code

[os-litant]

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

Transliteration key (the GitHub body sanitizer eats angle-bracket-shaped fragments, so four spellings below are written without angle brackets; everything else is the file verbatim):
[[os:check]] = the HTML-comment-shaped example marker · [T] = the type parameter T in angle brackets · [IDataEngine] = the type argument IDataEngine in angle brackets · [own ledger] = the placeholder argument own ledger in angle brackets.

---

Audit findings — skills/objectstack-api/ (read-only)

Pinned ref: objectstack origin/main = a59f78d. (Checkout HEAD is a39b02a, an
ancestor; git diff a59f78d HEAD -- skills/objectstack-api/ is empty, so every
span below is byte-identical at the pinned ref.)

Package price tag (node scripts/check-skills-token-ratchet.mjs)

File	Tokens	Ceiling	Headroom
skills/objectstack-api/SKILL.md	6311	6319	8
skills/objectstack-api/evals/README.md	546	546	0
skills/objectstack-api/references/_index.md	888	generator-owned	—
authored total	6857	6865	8
paid per customer session	7745

607 + 49 + 49 = 705 lines. No rules/**, no contracts/**, zero eval fixtures.

Real-usage corpus (what was grepped)

examples/** (app-showcase, app-crm, app-todo, embed-objectql), packages/apps/**
(account, setup, studio), packages/adapters/hono, packages/plugins/**,
packages/rest, packages/spec/src/api/**.

Surface	Real usages	Where
declarative apis: (ApiEndpoint)	2	examples/app-showcase/src/system/apis/index.ts:65,99; registered examples/app-showcase/objectstack.config.ts:250
code route on http.server	3	examples/app-showcase/src/system/server/recalc-endpoint.ts:52,61; packages/plugins/plugin-sharing/src/sharing-plugin.ts:790; packages/plugins/plugin-approvals/src/approvals-plugin.ts:356
public anonymous form (sharing.allowAnonymous + publicLink)	2	examples/app-showcase/src/ui/views/inquiry.view.ts:72-73; examples/app-crm/src/views/lead.view.ts:77-78
defineDatasource	4	examples/app-showcase/src/system/datasources/showcase-external.datasource.ts:28; examples/app-crm/src/datasources/crm.datasource.ts:15,44
apiEnabled	1	examples/app-todo/src/objects/task.object.ts:194
apiMethods	0	—
RestApiEndpointSchema	0	— (see API-E-01)
ServiceInfo	0	—
projectResolution	0	—
realtime subscription authoring	0	only requires: [… 'realtime'], examples/app-showcase/objectstack.config.ts:107
*.endpoint.ts files	0 repo-wide	find . -name '*.endpoint.ts' → empty

So 3 api-owned real authoring patterns (declarative apis:, http.server mount,
public form), plus one (defineDatasource) owned by objectstack-data.

---

Findings

id	dim	file:span	evidence (measured)	proposal	Δtok	gate ① decision changed? ② deletion instead? ③ construct?	conf	human-floor
API-E-01	E	SKILL.md:117-146	The package's leading [[os:check]] example teaches RestApiEndpointSchema "via the REST API plugin". Measured: (a) grep -rn 'RestApiEndpoint' packages/ examples/ excluding packages/spec/src/api/plugin-rest-api.* → 0 hits; (b) there is no plugin-rest-api package (ls packages/plugins/ | grep -i rest → empty); (c) createRestApiPlugin(config: RestApiPluginConfig) (packages/rest/src/rest-api-plugin.ts:95-105) accepts only {serverServiceName?, protocolServiceName?, kernelManagerServiceName?, api?: RestServerConfig} — no endpoints key; (d) its container RestApiRouteRegistrationSchema (packages/spec/src/api/plugin-rest-api.zod.ts:185-232) is the PLATFORM's own route catalogue — its @example is the built-in /api/v1/data group; (e) plugin-rest-api.zod.ts is absent from this package's SKILL_MAP (packages/spec/scripts/build-skill-references.ts:110-119) and from references/_index.md; (f) the skill's own SKILL.md:144-145 concedes the declarative surface is "usually the better one".	DELETE (fold the one live fact — auth is flat public + permissions — into the D6 section)	-294	① yes — stops the agent authoring a shape nothing mounts. ② deletion IS the fix. ③ n/a	HIGH	yes
API-H-01	H	evals/README.md:1-49 (whole file, 546 tok)	Ships zero evals and says so: :41 "⚠️ Not yet implemented — This is a placeholder for future development." 36 of 49 lines are an ASCII tree of 10 files that do not exist (:13-29) plus a maintainer-facing "Contributing" procedure (:43-49). Paid in every customer session. The maintainer-established minimal form is skills/objectstack-data/evals/README.md — 11 lines / 143 tok, same warning + a one-paragraph candidate list — for a package 2.2× this one's size (13892 tok). api's is the 2nd-largest eval README in the bundle (query 558, api 546, platform 514, automation 414, i18n 410, ai 315, ui 289, data 143).	REWRITE-AS-CONSTRUCT → the objectstack-data 11-line form	-400	① no decision is changed by a directory listing of absent files. ② yes. ③ yes — one candidate-scenario paragraph	HIGH	no
API-C-01	C	SKILL.md:472-510	"Datasource Configuration" + "Supported Drivers" (316 tok). Anchor exists: skills/objectstack-data/rules/datasources.md:1-80 (903 tok — schemaMode table, auto-connect rules, credentialsRef fail-closed, the double write opt-in), linked from skills/objectstack-data/SKILL.md:319. Driver table duplicated worse than skills/objectstack-platform/SKILL.md:353-357, which carries package names, class names and the Turso "Cloud / EE only … UnsupportedDriverError" caveat that objectstack-api/SKILL.md:508 omits. Ownership is settled by the generator: data/datasource.zod.ts is in objectstack-data's SKILL_MAP (build-skill-references.ts:89) and not in objectstack-api's (:110-119).	DELETE (keep at most a one-line pointer to objectstack-data)	-300	① no — the decision is already made in two other packages. ② yes. ③ n/a	HIGH	yes
API-C-02	C	SKILL.md:513-538	"Inter-Service Communication" (226 tok). Dedicated anchor: skills/objectstack-platform/rules/service-registry.md (2329 tok — signature :14, lifetimes :69, init-vs-start timing :200,214, missing-service failure :229), plus skills/objectstack-platform/SKILL.md:825 ctx.getService[IDataEngine]('objectql') — the same type this section uses. The api version is strictly worse: SKILL.md:532 declare const kernel: { getService[T](name: string): T } fabricates the host shape, so the os:check marker on :528 proves nothing about the real PluginContext; every real call site is await ctx.getService(…) (async) — examples/app-showcase/src/system/server/recalc-endpoint.ts:52, packages/apps/{account,setup,studio}/src/index.ts:{60,55,68}, 115 sites under packages/plugins/.	DELETE	-226	① no. ② yes. ③ n/a	HIGH	yes
API-C-03	C	SKILL.md:458-468	"Security Layers" table + "Key rule" callout (138 tok). Names no authorable key. RBAC anchor: skills/objectstack-data/SKILL.md:590-620 (definePermissionSet, the permissions: vs permissionSets: trap, the bit list) — which even cross-links enable.apiMethods at :622. RLS anchor: skills/objectstack-data/SKILL.md:690-745. Internal duplicate too: the callout :466-468 restates the table's own Description column verbatim in prose.	DELETE	-138	① no. ② yes. ③ n/a	HIGH	yes
API-D-02	D	SKILL.md:384-396	"Handler Status" 3-row table, immediately neutralised by its own callout :393-395: "handlerStatus is DOCUMENTATION — nothing reads it at runtime. The dispatcher's 501 NOT_IMPLEMENTED comes from the endpoint executor, never from this field." (Confirmed: packages/runtime/src/endpoint-executor.ts:320 emits DispatcherErrorCode.enum.NOT_IMPLEMENTED.) A table teaching a field with no reader, on a schema with no consumer (API-E-01). handlerStatus: 'implemented' also appears in the dead example at :136.	DELETE (table + callout; and the key from :136 if that example survives)	-130	① no — the text says the field changes nothing. ② yes. ③ n/a	HIGH	no
API-B-01	B	SKILL.md:419-429	Third rendering of the same three fields. :140-142 already states "There is no name, request, response, or auth field on this schema … auth is the flat public + permissions pair"; :419-420 restates "There is no nested auth block on endpoints"; :422-429 is an unmarked fragment re-showing public/permissions/rateLimit already shown in the os:check block at :126-137.	DELETE :419-429, keep :431-435 (the D6 cross-ref)	-120	① no — third statement of one rule. ② yes. ③ n/a	HIGH	no
API-D-01	D	SKILL.md:346-366	Health/readiness (139 tok): a JSON response body the customer never authors, plus /ready semantics. The section's own :348 says "Every ObjectStack deployment exposes GET /api/v1/health" — i.e. nothing to configure or author. Client-consumption content the frontmatter :8-9 explicitly disclaims ("that is just standard HTTP — no skill needed").	REWRITE-AS-CONSTRUCT → one line: "GET /api/v1/health (success envelope) and GET /ready (200 running / 503 booting) exist on every deployment; per-service status is GET /api/v1/discovery."	-120	① no. ② yes, mostly. ③ yes — one line	MED-HIGH	no
API-D-03	D	SKILL.md:544-547, 556-558	Best Practice 1 ("Version your APIs — always use /api/v1/ prefix") duplicates the naming rule at :273 ("Always prefix with /api/v1/ for versioning") and is wrong-headed for the surface the package most wants used: for declarative apis: the prefix is not the author's choice (:187-190 carve-out). Best Practice 4 ("Document every endpoint with description and response schemas") names no key and no gate.	DELETE both	-109	① no. ② yes. ③ n/a	MED-HIGH	no
API-B-05	B	SKILL.md:22-28	Preamble ("Expert instructions for designing REST APIs, service contracts, and integration protocols … This skill covers endpoint definitions, API discovery, authentication, dispatcher configuration, and inter-service communication patterns.") restates the frontmatter description (:3-12) in less-precise words, above the fold, before any rule.	DELETE	-78	① no. ② yes. ③ n/a	HIGH	no
API-F-05	F	SKILL.md:316-344	"Service Discovery" + the ServiceInfo os:check example (257 tok). grep -rn 'ServiceInfo' examples/ packages/apps/ → 0. ServiceInfo is a response shape (GET /api/v1/discovery), never authored. api/discovery.zod.ts is not in this package's SKILL_MAP (build-skill-references.ts:110-119) and not in references/_index.md.	RETIRE-SURFACE (keep one line: per-service status is GET /api/v1/discovery)	-230	① no — an author constructs no ServiceInfo. ② yes. ③ yes — one line	MED-HIGH	yes
API-A-01	A	SKILL.md:31-39	"When to Use This Skill", 6 bullets, 110 tok. Three misroute: :35 "setting up service discovery and health checks" — the body's own :348 says every deployment already exposes them, nothing to set up; :37 "You need to understand the dispatcher routing system" — comprehension, not an authoring task; :38 "integrating external APIs via datasource connectors" — datasources are database connectors and are objectstack-data's domain (API-C-01). None of the three names an authorable artefact. The two newest siblings replaced this section with a routing table (objectstack-data/SKILL.md:29-34, objectstack-query/SKILL.md:22-28).	REWRITE-AS-CONSTRUCT → 4-row "Skill Boundaries" table matching data/query	-60	① yes — stops wrong-package loads. ② partial. ③ yes — table	MED-HIGH	no
API-F-04	F	SKILL.md:275-279	Environment-scoped routes + projectResolution (85 tok). grep -rn projectResolution examples/ packages/apps/ packages/adapters/ → 0. Authorable (packages/spec/src/stack.zod.ts:549) but unused in every shipped app.	RETIRE-SURFACE (or one line)	-85	① rarely. ② yes. ③ n/a	MED	yes
API-B-02	B	SKILL.md:203-209	A second "run the gate" block inside "Five publish gates" — objectstack validate # or: os build — same gates — duplicating the package's own Verify your work section at :584-597, 384 lines later, which runs the identical gates.	MERGE-INTO SKILL.md:584-597	-55	① no — same gate twice. ② yes. ③ n/a	HIGH	no
API-D-04	D	SKILL.md:569-576	Common Pitfalls 1-4. #1 ("Use FLS (field-level security) … to restrict what is visible") names a surface with no authorable spelling anywhere in the bundle: grep -rn 'fieldLevelSecurity|fieldPermissions' packages/spec/src --include=*.zod.ts → one hit, packages/spec/src/api/protocol.zod.ts:2465, on a response schema; no published skill teaches how to author it — unactionable advice. #2 "Default page size should be 20–50, with a max of 200" matches no platform constant (grep -rn 'maxPageSize|defaultPageSize|MAX_PAGE|DEFAULT_LIMIT' packages/spec/src packages/rest/src → 0; the only 200/50 pair, packages/rest/src/rest-server.ts:8338, is the sys_import_job list route alone) and pagination is objectstack-query/rules/pagination.md's anchor. #4 "Ignoring rate limiting" duplicates the armed-budget rule at :216-230.	DELETE #1, #2, #4	-95	① no — #1 cannot be acted on, #2/#4 are already stated or generic. ② yes. ③ n/a	MED-HIGH	yes (#1 removes published capability text)
API-D-05	D	SKILL.md:191-198	Carve-out rationale after the rule: "This is what makes route ownership structural: no built-in domain lives under apps/, and two packages cannot collide because their namespaces differ", plus "there is deliberately no derivation from manifest.id, because an outward URL contract must not move because a package id was rewritten", plus :196-198 "Note the ordinary naming rules above still apply inside the subpath…". The rule itself is :188-190.	DELETE the two why-paragraphs, keep the rule	-90	① no — the rule already decides it. ② yes. ③ n/a	MED	no
API-B-03	B	SKILL.md:65-71, 283-313, 559-563	The apiMethods six-primitives / derived-verbs rule is stated three times in one file (Key-rule callout; a 31-line two-table expansion; Best Practice 6 restating "upsert is DERIVED (create ∧ update)"), and a fourth time in skills/objectstack-data/SKILL.md:95. The derived table's own content is decision-thin — 3 of its 8 rows say "Gating only — no dedicated generated route today" and 2 (restore, purge) derive from "never (trash retired)". apiMethods has 0 real usages.	MERGE the three into one table row; drop the restore/purge/history rows (source: packages/spec/src/data/object.zod.ts:46-55 already ships the FROM→TO prescription as a runtime warning)	-180	① yes — once. ② yes, twice over. ③ yes — one table	MED	yes
API-A-02	A	SKILL.md:3-12 vs body	Frontmatter promises "error envelopes, batch/versioning contracts". Body coverage of batch = two route lines (:56-57) + one best-practice clause (:562-563); of versioning = "always prefix /api/v1/" (:273, :544). Both batch.zod.ts and versioning.zod.ts are listed as Core schemas in the package's own references/_index.md:13,18. Measured: versioning.zod.ts has zero consumers repo-wide outside packages/spec/src/type-alias-convention.pin.test.ts:567,569 — declared-not-implemented surface, so there is nothing true to teach.	DELETE "versioning" from the description; keep "batch" and pay for one batch line with API-B-03	-10	① yes — stops the agent loading this package expecting a versioning contract. ② yes. ③ n/a	MED-HIGH	yes (frontmatter)
API-A-03	A	SKILL.md:8-9 vs :73-94, :316-366	The description forbids the client seat — "Do not use for: consuming an ObjectStack API from a client (that is just standard HTTP — no skill needed)" — while 663 tok of body teach exactly that: /meta client query-param contracts (?preview=draft, ?package=, ?include=content, :83-94) and discovery/health response shapes (:316-366). Measured client-side usage of those params in examples/ + packages/apps/: preview=draft 0, packageId= 0, include=content 0 (the only hits are producer-side, packages/rest/src/rest-server.ts:5061, packages/runtime/src/domains/meta.ts:67).	MOVE-TO — cut :316-366 (see API-F-05/API-D-01); demote :83-94 to a 2-line pointer	-150	① yes — the contradiction currently makes both readings defensible. ② yes. ③ yes — pointer	MED	yes
API-G-01	G	SKILL.md:206 vs :590	Two spellings of one command in one file: objectstack validate (:206) and os validate (:590). Both binaries exist (packages/cli/package.json:17-20) but os is the bundle-dominant form (15+ sites across siblings; the only other objectstack validate uses are objectstack-automation/SKILL.md:146 and a package.json script at objectstack-platform/SKILL.md:611). Subsumed by API-B-02.	DELETE (with API-B-02)	0	① no. ② yes. ③ n/a	HIGH	no
API-G-02	G	SKILL.md:481	import { defineDatasource } from '@objectstack/spec' (root barrel) contradicts (a) both real usages — examples/app-showcase/src/system/datasources/showcase-external.datasource.ts:3 and examples/app-crm/src/datasources/crm.datasource.ts:3, both from '@objectstack/spec/data' — and (b) the package's own references/_index.md:45-49: "Runtime values: import from the matching subpath … The root barrel re-exports the common factories, but not every symbol — when in doubt, use the subpath." Compiles (it is os:check-marked), so it is a convention break, not rot. Moot if API-C-01 lands.	DELETE with API-C-01, else REWRITE to the subpath	0	① yes — teaches the discouraged import. ② yes. ③ n/a	HIGH	no
API-G-03	G	SKILL.md:277	"(project scoping in the REST server)" uses the retired workspace word against skills/README.md:88 Conventions — "v5.0 vocabulary — runtime workspace is environment, not project" — in the same sentence as the /api/v1/environments/:environmentId/... route. The identifiers are genuinely enableProjectScoping / projectResolution (packages/rest/src/rest-server.ts:3574), so this is a gloss problem, not a falsehood. Moot if API-F-04 lands.	DELETE with API-F-04	0	① no. ② yes. ③ n/a	MED	no
API-G-04	G	package-wide	Retired-spelling sweep (silently|ignored|dropped|legacy|deprecated|M9|v5\.0|OLD|NEW) over all three files returns only legacy_erp (an example variable name, :483-484) and "mongo is a legacy alias" (:505, accurate). No residue. Protocol references are uniformly 17.x (:14,152,211,247) with one correct historical 16.x (:579).	none	0	—	HIGH	no
API-E-02	E	SKILL.md fences	Gate is packages/spec/scripts/check-skill-examples.ts (marker = [[os:check]] on the line directly above a bare ```ts/```typescript fence). Counted: 8 TypeScript fences (:123,171,222,328,422,438,480,529), 6 marked (:122,170,327,437,479,528), 2 unmarked (:222, :422). Both unmarked are genuine object-literal fragments that cannot compile standalone — no unmarked fence would plausibly fail a type-check; no rot found. One marked block is however gate-proof-free: :532 declare const kernel: { getService[T](name: string): T } type-checks against a locally declared shape, not the real host (see API-C-02).	note only	0	—	HIGH	no
API-F-01	F	GAP — SKILL.md:164 only	http.server code mount: 3 real sites (examples/app-showcase/src/system/server/recalc-endpoint.ts:48-61, packages/plugins/plugin-sharing/src/sharing-plugin.ts:790, packages/plugins/plugin-approvals/src/approvals-plugin.ts:356) and the package names it in one table cell — "Mount it on http.server" — with no example. Missing decisions the real sites all make: mount on kernel:ready (the matcher freezes at kernel:listening — recalc-endpoint.ts:13-15); the dual-name lookup readServer('http.server') ?? readServer('http-server') that both plugins do; await ctx.getService(…) is async; the handler signature is (req, res) with res.status(n) / res.json(body). This is the only code-route pattern the repo actually ships.	ADD — 10-line os:check-able canonical example, paid by API-E-01 (-294) in the same file	+130	① yes — the top uncovered real task. ② no. ③ yes — canonical example	HIGH	yes (adds capability text)
API-F-02	F	GAP — SKILL.md:548-555	ADR-0112 error-code ledger. The frontmatter promises "error envelopes"; both contract.zod.ts and error-code-ledger.zod.ts are already in this package's references/_index.md:23-24. The body never states the load-bearing rule: the error.code vocabulary is two-tier (StandardErrorCode ∪ registered ledger) and an unregistered code fails schema parse → fails the envelope conformance suites → fails CI (packages/spec/src/api/error-code-ledger.zod.ts:14-17); a downstream product repo maintains its OWN ledger and composes envelopeViolations(body) (shape) with makeApiErrorSchema([own ledger]) (vocabulary) (:19-35; functions at packages/spec/src/api/contract.zod.ts:146,215; envelopeViolations has 135 call sites repo-wide). This is precisely the third-party author's decision and it is absent.	ADD — 5-line construct, paid by API-C-02 (-226) in the same file	+120	① yes — a third party otherwise invents codes that fail CI. ② no. ③ yes — construct	HIGH	yes
API-F-03	F	SKILL.md:575-576	Common Pitfall 3 says "Concurrent updates should use optimistic locking (version field) and return 409 on conflict" — naming neither real spelling. The generated PATCH /api/v1/data/{object}/:id route implements OCC via If-Match header OR expectedVersion in the JSON body (body wins when both present), the token is "typically the updated_at value the client read", mismatch → 409 CONCURRENT_UPDATE, and "" is refused 400 VALIDATION_FAILED (packages/rest/src/rest-server.ts:7711-7721; packages/spec/src/api/protocol.zod.ts:2100-2102; code registered at packages/spec/src/api/error-code-ledger.zod.ts:168).	REWRITE-AS-CONSTRUCT — replace the generic sentence with the two spellings, paid by API-D-03 (-109)	+40	① yes — turns unactionable advice into a copyable contract. ② no. ③ yes	HIGH	yes
API-F-06	F	SKILL.md:404-411	Realtime: 0 authoring usages in examples/ or packages/apps/. The section is already pointer-style (good), but 2 of its 6 lines document declared-but-unenforced keys: "the RealtimeEventType enum is declared but not yet enforced — the runtime emits data.record.* event names instead" and "(filters not enforced)". An author cannot act on either; under ADR-0049 enforce-or-remove these are upstream removal candidates, not skill content.	DELETE the two unenforced-key notes; keep the two pointers	-45	① no — nothing to decide about an unenforced key. ② yes. ③ n/a	MED	yes
API-B-04	B	SKILL.md structure	607 lines, 11 top-level ## sections, no rules/** split — the whole package is one file plus a generated index. Order buries the two most decision-changing blocks: the apis: vs code-handler choice table (:159-168) and the D6 armed-budget rule (:216-230) sit after 148 lines of route tables and a dead-surface example (API-E-01). Comparable packages split (objectstack-data 8 rules/*, objectstack-query 3, objectstack-platform 4). Not itself a defect at 6.3k tok — but the 4 sections proposed for deletion above (C-01, C-02, C-03, E-01) are exactly the ones that belong elsewhere, so the fix is removal, not a split.	note only (see the deletions)	0	—	MED	no

Totals

• Confident reductions (HIGH/MED-HIGH): E-01 294 + H-01 400 + C-01 300 + C-02 226 + C-03 138 + D-02 130 + B-01 120 + D-01 120 + D-03 109 + B-05 78 + F-05 230 + A-01 60 + B-02 55 + D-04 95 + A-03 150 + A-02 10 = -2,415
• Lower-confidence (MED): B-03 180 + D-05 90 + F-04 85 + F-06 45 = -400
• Paid additions: F-01 +130, F-02 +120, F-03 +40 = +290
• Net at the confident tier alone: -2,125 on 6,857 authored tokens = 31%.
  With the MED tier: -2,525 = 37%.

Incidental falsehoods

None. Every behavioural claim spot-checked against the implementation held
(ApiMethod/ApiOperation split vs packages/spec/src/data/object.zod.ts:35-80;
the five publish gates vs packages/spec/src/api/endpoint-publish-gate.ts:27-32;
AuthProvider / LoginRequestSchema vs packages/spec/src/api/auth.zod.ts:18-25,57;
handlerStatus has no runtime reader vs packages/runtime/src/endpoint-executor.ts:320;
'data' and 'objectql' both register IDataEngine vs
packages/objectql/src/plugin.ts:395,397; every node_modules/@objectstack/spec/src/**
pointer resolves to a real file, ui/sharing.zod.ts:59 and ui/view.zod.ts:3031
included). Two items are unactionable rather than false and are filed as
API-D-04 (#1 FLS) and API-F-03 (vague OCC).

---

Generated by Claude Code