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

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

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.
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).
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.

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

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

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

skills(api): cut other packages' anchors and the dead RestApiEndpoint…

docs(skills): regenerate skills index after the objectstack-api front…

chore(gates): ratchet the role-word baseline down after API-C-03

os-dev-report

{
  "issue": 14304,
  "status": "done",
  "branch": "claude/issue-14304-skills-api-optimization",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14448",
  "premise_still_valid": true,
  "summary": "All 22 filed DELETE/MERGE/REWRITE findings at HIGH, MED-HIGH and MED implemented in skills/objectstack-api/SKILL.md, plus the three funded additions. 6311 to 4635 tokens (-1676, -26.6%); ceiling 6319 unchanged, no new file, no file deleted, ratchet script untouched. evals/README.md untouched (API-H-01 deferred to #14296 item 2), so the PR opens with 'Part of #14304' and the card stays open. Three deviations, all declared in the PR body: (1) FOURTH FILE scripts/role-word-baseline.json - check:role-word went RED on this branch with its ratchet-DOWN remedy because API-C-03 deleted the file's one baselined occurrence of the reserved word; the gate names --update as the author's path, so the entry is dropped (43 to 42 files, no other row moves), committed separately. (2) PREMISE FALSE on one clause of funded addition 1: the audit's 'getService is async' is wrong for the real host - PluginContext.getService(name) at packages/core/src/types.ts:36 is SYNCHRONOUS and THROWS; measured 0 awaited vs 112 sync call sites in packages/plugins non-test, and the audit's evidence site is the showcase's own locally declared RecalcHostContext shim, i.e. the same fabricated-host defect API-C-02 was deleted for. The true rule is written instead. (3) The new http.server example is deliberately NOT os:check-marked - assumption 3 measured directly, see tests. The :532 marked block needed neither fix nor unmark: it is deleted with API-C-02. Net delta lands 49 tokens (2.8%) short of the -1725 dispatch floor; itemised rather than smoothed in the PR body - the three additions cost 239 tokens over budget after two trimming passes, the deletions cut about 190 more than the audit's estimates. skip-changeset and needs:contract-review applied to the PR, needs:contract-review to the card; all label writes were read-modify-write and read back (PR reads back exactly documentation, size/m, skip-changeset, needs:contract-review; card exactly its 4 plus needs:contract-review; nothing stripped). PR stays DRAFT.",
  "tests": "All gates run at head sha 19ee5853, every exit code captured by redirect-then-capture (never after a pipe). Gate union re-derived twice with 'node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands' - once after gen:skill-docs, once after the final commit - 42 commands, all 42 run. RESULT: 41 green, 1 NOT MEASURED, 0 red. Named gates: check-skills-token-ratchet exit 0, 'skills/objectstack-api/SKILL.md is 4635 tokens (ceiling 6319; headroom 1684)' and '38 authored bundle file(s) within their ceilings'. check:skill-examples exit 0, '255 prose examples type-check across 3 surface(s) - every marked block parsed, so tsc ran the SEMANTIC pass on all of them'. check:skill-compatibility exit 0, '11 SKILL.md file(s) reconciled against 78 workspace packages'. check:skill-identifier-liveness exit 0, 'Leg 1: 488 citation(s) over 48 published file(s); Leg 2: 9 registered exhaustive section(s), 0 ledgered gap(s)' (baseline 500 citations; the drop is the deleted tables). check:skill-docs exit 1 BEFORE regeneration on both generated files, exit 0 after, 'Skill docs in sync'. check:role-word exit 1 then exit 0 after the ratchet-down. check-nul-bytes exit 0, 7875 files, plus a direct control-byte grep over the three edited files, no hits. NOT MEASURED: check-test-completeness exits 3, its own PREREQUISITE code - it needs a saved 'turbo run test' log; its own text says 'Nothing was measured, it is NOT a finding'. CI supplies it. Two further gates were exit-3/exit-1 PREREQUISITE states on the first pass and green after the closures were built, not after any edit: check:doc-formula-expressions and check:doc-security-posture (needed @objectstack/formula built), check:docs (needed gen:schema). Heavy steps ran through scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-14304 set before the first attempt; both acquisitions printed 'VERDICT command-exit 0' (build: waited 138s held 441s; skill-examples: waited 303s held 18s). Build was 'pnpm --workspace-concurrency=2 --filter @objectstack/spec... --filter @objectstack/client-react... --filter @objectstack/formula... build' so check:skill-examples could refuse rather than false-green. MUTATION PROBE (assumption 3, the only mutation): a temporary os:check-marked block importing PluginContext from @objectstack/core was appended to SKILL.md under a trap with an absolute REPO_ROOT-derived path. No rebuild was needed - the mutated artefact is the markdown the gate reads directly, not a dist product. Mutation confirmed ON DISK before measuring: git hash-object moved 99267f60 to aa09e9d9, and grep counted 1 hit each for the injected import and heading; the run would have aborted non-zero on a zero-hit anchor. Result: 'error TS2307: Cannot find module @objectstack/core' - the real PluginContext is unreachable from the skills os:check surface, so the new example stays unmarked. Restore confirmed by observation, not by exit code: worktree blob hash back to 99267f60 = the HEAD blob hash, 'git diff HEAD' empty, git status clean, and 0 grep hits for both probe strings. Every source claim written into the skill was re-verified by content on this branch's base (file:line list in the PR body); assumption 4's greps carried a positive control (the same grep for ApiEndpoint returns many hits).",
  "mcp_calls": "19 - REST is 403 for this session (measured: repo-scoped GET /repos/objectstack-ai/objectstack returns 403 'GitHub access is not enabled for this session', gh CLI absent), so ALL GitHub reads and writes went through MCP; channel switch declared. Dedupe before filing was one targeted search_issues, no wide listing.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #14446: declared != enforced (ADR-0049) - RealtimeEventType (packages/spec/src/api/realtime.zod.ts:33-40) spells record.* while the platform emits data.record.* (api/events.zod.ts:139-141), and SubscriptionSchema.filters is z.unknown().optional() (realtime.zod.ts:49); finding label, unassigned, no pm-state, no priority; dedupe searched first, the four nearest cards #4602 #4626 #4673 #9055 are all closed and none covers this pair",
    "NOT filed, reported in the PR body under 'follow-up for objectstack-data / objectstack-platform': neither anchor names the driver ID vocabulary an author writes in defineDatasource (postgres, mysql, mongodb, sqlite, sqlite-wasm, turso, memory, and the mongo alias) - the deleted objectstack-api table did. Nothing is lost (the pointer names the authoritative source packages/spec/src/data/driver/config-registry.zod.ts:163), but a row in objectstack-data/rules/datasources.md is the right home. Left as a PR-body note rather than a card because it is one row inside a sibling flight already in review; PM to route if that flight has closed"
  ]
}

Generated by Claude Code

ACCEPT — skills-lane seat (session session_01LraLgQVGq8egUwfYZpbYt1), reviewer of record, verified against GitHub not the report.

PR skills(api): optimization flight — RestApiEndpointSchema example and other packages' anchors cut, the apiMethods rule stated once, http.server mount / error ledger / OCC taught (net −1,676 tokens) #14448 exists, is DRAFT, targets main, first line Part of #14304 (API-H-01 deferred to [Decision] Skills optimization program — batch 1 (4 items): new-file ceilings for splits · planned-eval stubs · react-blocks double rendering · published pm-dispatch scope #14296 item 2 keeps the card open; pm:dispatched → pm:blocked by hand at merge, deferred half re-dispatched on this card after the ruling). Whole-body closing-keyword scan clean; the "Part-of PR must not also close its card" check is green.
Changed files (4, read from the diff): skills/objectstack-api/SKILL.md 6,311 → 4,635 tokens (−1,676, −26.6%; ceiling 6,319 untouched; 607 → 428 lines); skills/README.md + content/docs/ai/skills-reference.mdx regenerated (frontmatter-derived); scripts/role-word-baseline.json −1 row — accepted under the four-condition rule for gate-prescribed fallout (API-C-03 deleted the file's one baselined occurrence, check:role-word went red with its own ratchet-DOWN remedy, the entry drops and no other row moves; same defect class, mechanical, no other open PR claims the path, same gate family). No new file, no deletion, no ratchet-script edit, no content/docs/releases/.
Changeset: skip-changeset on the PR — correct (nothing released by any package; Check Changeset green).
CI on head 19ee5853: all 39 check runs completed success or skipped by path filter — Lint & Repo Gates green at 07:38Z, Type Check ×4, Test Core 1–6, Build Docs, all PR guards. Local union 41/42 exit 0 with check-test-completeness NOT MEASURED — consistent with CI.
Deviations accepted as reported: net −1,676 vs the −1,725…−2,100 target, 49 tokens (2.8%) short with the cause itemised (the three additions cost 239 over their funding after two trims; closing the gap would cut content no finding covers); the new http.server block deliberately unmarked because the skills os:check surface cannot resolve @objectstack/core (measured by mutation probe, restore proven by blob hash); the :532 marked block deleted with API-C-02 rather than fixed.
premise_false accepted, and it is the right call: the audit's "getService is async" rested on a locally declared shim in recalc-endpoint.ts; the real PluginContext.getService<T>(name): T is synchronous and throws (packages/core/src/types.ts:30-36, 0 awaited vs 112 sync call sites). The skill now teaches the true rule, which is exactly why the dual lookup needs one try per name.
Follow-ups recorded (seat ledger): the driver id vocabulary row belongs in objectstack-data/rules/datasources.md (neither anchor names postgres / mysql / mongodb / sqlite / sqlite-wasm / turso / memory + the mongo alias; config-registry.zod.ts:160-166 is the source) — routed to the deferred round on Skills optimization flight — skills/objectstack-data: RESTRUCTURE (≈ −10,150 tok, −22%) — hooks taught twice across two files, generic-JS patterns, 3.3% example gate coverage, sharingModel used by 31/31 objects and explained nowhere #14297. Out-of-scope card filed by the dev: declared ≠ enforced (ADR-0049): RealtimeEventType spells record.* while the runtime emits data.record.*, and SubscriptionSchema.filters is z.unknown() nothing reads #14446 (realtime declared ≠ enforced).
Governed face (skills/**) ⇒ terminal = human merge. Review requested from the two authorized approvers with the draft bit held; ⛔ not flipped ready, not enqueued.

Contract review (clause ②, in-seat; served model read claude-fable-5-1 = CONTRACT_REVIEW_TIER) — PASS.
① Derived judgments verified at source: (1) getService synchronous, @throws Error if service not found (packages/core/src/types.ts:30-36): correct. (2) http.server dual lookup, canonical first (plugin-sharing/src/sharing-plugin.ts:790, plugin-approvals/src/approvals-plugin.ts:356; hono-plugin.ts:228 provides both names): correct. (3) mount on kernel:ready, not later — Hono "seals the matcher the first time a request is matched" (packages/spec/src/contracts/plugin-lifecycle-events.ts:81; recalc-endpoint.ts:110-112 hooks kernel:ready); IHttpResponse.status(code): IHttpResponse chains (contracts/http-server.ts:77): correct. (4) ADR-0112 ledger is two-tier, "An unregistered code fails schema parse — which fails the envelope conformance suites — which fails CI", framework packages only (packages/spec/src/api/error-code-ledger.zod.ts:1-14); makeApiErrorSchema (contract.zod.ts:146) and envelopeViolations (:215): correct. (5) OCC: If-Match header or expectedVersion body, bodyVersion ?? ifMatchHeader so the body wins (packages/rest/src/rest-server.ts:7711-7720); token typically updated_at, 409 CONCURRENT_UPDATE, "" refused 400 VALIDATION_FAILED (protocol.zod.ts:2097-2102 describe; ledger :168; pinned rest-unclassified-fault-status.test.ts:230): correct. (6) authRequired: false obliges a rateLimit (ADR-0121 D6; stack.zod.ts:510): correct. (7) driver id vocabulary pointer (config-registry.zod.ts:160-166): correct. Carried over unchanged from base and not re-adjudicated: /ready 200/503, restore/purge never derive (trash retired), the derived-operation table rows, manifest.namespace explicit (endpoint.zod.ts:159-160 agrees).
② Semver: no release; skip-changeset consistent. ③ Boundary flags: open_questions empty; API-F-06 filed as #14446; API-H-01 deferred. No flag left open.
needs:contract-review stripped from both carriers in this same write (provenance: maintainer ruling 2026-08-31 — the dispatch seat performs the in-seat contract review at tier and clears the gate itself; governed face keeps the draft-only terminal).

Generated by Claude Code

Round 1 MERGED — PR #14448 landed on main at 09:03Z (approved by os-zhuang). The card stays open for its second round.
Session: session_01LraLgQVGq8egUwfYZpbYt1

Ruling landed. #14296 was ruled 1A 2A 3A 4A at 09:27Z (comment 5507419465). Item 2 = A: the planned-eval stubs are deleted, ceilings step down with them; real fixtures stay. This package's deferred half is exactly that: skills/objectstack-api/evals/README.md (546 tokens, a template listing files that do not exist) is deleted and its row dropped from scripts/check-skills-token-ratchet.mjs (a deleted file ⇒ drop its ceiling row only — the one edit to the ratchet script a flight may make).

State: pm:dispatched → pm:queue (not pm:blocked — the blocker is gone). Round 2 scope: one light flight on a fresh branch from main, two files (the deletion + the ratchet row), Part of #14304 → this round CLOSES the card, so its PR may say Fixes #14304 once the seat confirms nothing else is deferred here; governed ⇒ draft; no contract claims ⇒ no needs:contract-review. The PR body quotes the ruling.

Generated by Claude Code

Claim: PM loop round 4 — second round on this card
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14304-api-eval-stub-removal (fresh from origin/main; round 1's branch is merged and is not reused)
Worktree: objectstack-issue-14304-r2
Domain: domain:skills
File surface: DELETE skills/objectstack-api/evals/README.md; drop its ceiling row from scripts/check-skills-token-ratchet.mjs (the one edit to that script a flight may make); ⛔ nothing else — no prose edit anywhere, no regeneration unless a drift gate names it
Container & model: S (two-file mechanical deletion under a ruling; no contract claim), mode:subagent, model: sonnet — the floor of the tier ladder; the seat reviews the diff by hand
Clause-②: no — nothing here states a contract; ⛔ no needs:contract-review
Ruling executed: #14296 item 2 = A (comment 5507419465, 09:27Z) — planned-eval stubs deleted, ceilings step down; quoted in the PR body
Serial constraints cleared: no open PR touches skills/objectstack-api/**; the ratchet script is touched only to drop one row (the i18n flight #14315 will drop its own row — different line, merges clean); light flight, does not occupy a heavy slot (#14315 / #14316 in flight)

Landing form: if the seat's ACCEPT ledger above lists no other deferred item for this card, the PR closes it — first line Fixes #14304; otherwise Part of #14304. Governed ⇒ draft; skip-changeset.

Generated by Claude Code

Claim: dev seat (os-dev subagent of the dispatching PM session — same session id, distinct seat)
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14304-api-eval-stub-removal
Worktree: ../objectstack-issue-14304-r2 (fresh from origin/main at 53d36892)

Scope taken as dispatched (round 2, per the ruling landed above): git rm skills/objectstack-api/evals/README.md + drop its one ceiling row from scripts/check-skills-token-ratchet.mjs — the only edit to that script this flight makes. Verified before touching anything: ls skills/objectstack-api/evals/ shows only README.md (no other fixture), and every path the README lists under its ASCII tree is absent from the repo. ⛔ No prose edit anywhere, no other file, no regeneration unless a drift gate names the command.

Ruling executed: #14296 item 2 = A (comment 5507419465, 09:27Z) — planned-eval stubs deleted, ceilings step down; quoted in the PR body.

Landing form: the seat's ACCEPT comment above names the eval stub as the only deferred item for this card, so this round's PR closes it — first line Fixes #14304. Governed (skills/**) ⇒ stays draft; skip-changeset; no contract claim ⇒ no needs:contract-review.

Generated by Claude Code

skills(api): delete the planned-eval stub and drop its ceiling row

os-dev-report

{
  "issue": 14304,
  "status": "done",
  "branch": "claude/issue-14304-api-eval-stub-removal",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14564",
  "premise_still_valid": true,
  "summary": "Round 2 of #14304, executing #14296 item 2 = A (comment 5507419465): deleted skills/objectstack-api/evals/README.md (546-token planned-eval template listing 10 files that do not exist; verified evals/ held only that one file and every path its ASCII tree listed is absent from the repo) and dropped its ceiling row from scripts/check-skills-token-ratchet.mjs -- the only edit to that script. Two-file diff, 50 deletions, 0 additions, no ceiling raised, no new file, no other package touched. Per the seat's ACCEPT comment on round 1 (PR #14448), the eval stub was the only deferred item on this card, so the PR opens with 'Fixes #14304'. Labels: skip-changeset applied via the additive labels write and read back on the PR (exactly ['skip-changeset'], nothing else present to strip); no needs:contract-review (no contract claim). PR #14564 stays draft: skills/** is a governed surface, landing is the maintainer's by hand; no reviewers requested per dispatch (that is the seat's step).",
  "tests": "Reverse verification (the ratchet's own documented behaviour, #4690): after `git rm` with the ceiling row still present, `node scripts/check-skills-token-ratchet.mjs` exits 1 -- 'cannot read skills/objectstack-api/evals/README.md -- red, not a skip (#4690)'. After dropping the row, same command exits 0 -- '36 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted'. `--self-test` on the edited script: 64/64 cases pass (row is keyed by exact relative path; nothing else in the self-test's fixtures depends on it). Gate union re-derived after the final commit at head 5631fd8a: `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` -> 24 commands, all run, every exit code captured before any pipe (redirect-then-capture). 22 green / 0 red / 2 NOT MEASURED (node scripts/check-test-completeness.mjs exit 3 PREREQUISITE NOT MET -- no saved turbo-test log; pnpm --filter @objectstack/lint check:doc-formula-expressions exit 3 PREREQUISITE NOT MET -- @objectstack/formula not built, and this flight touches neither formula nor its docs, so CI supplies the real reading rather than building a closure to green an unrelated prerequisite on a two-file deletion). check:pm-dispatch-gates (self-test-heavy, its own header documents it can exceed an agent container's foreground cap) ran ~19 minutes and finished green on its own -- '1240 cases pass' -- confirmed by direct log polling rather than a monitor notification, per instruction. `pnpm --filter @objectstack/spec check:skill-docs` green with no regeneration needed (neither generated file lists evals/). `check:skill-identifier-liveness` and `check:skill-compatibility` both green and unaffected by the deletion. `node scripts/check-nul-bytes.mjs` clean. Remote head confirmed equal to the tree the gates read: `git push` reported 5631fd8a as the new remote tip, matching local HEAD exactly (no further edits after the gate run).",
  "mcp_calls": "8 -- issue_read get + get_comments on #14304, add_issue_comment (dev-seat claim), pull_request_read get on #14448 (reference), create_pull_request (#14564), issue_write labels update on #14564, pull_request_read get on #14564 (read-back verification), plus this report comment. No dedupe search needed -- no out-of-scope finding filed this round.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT — round 2, PR #14564 @ 5631fd8a, verified against GitHub, not the report.
Session: session_01LraLgQVGq8egUwfYZpbYt1

Diff read by the seat: exactly two files — skills/objectstack-api/evals/README.md deleted (49 lines, the planned-eval template) and one row removed from scripts/check-skills-token-ratchet.mjs (['skills/objectstack-api/evals/README.md', 546]); 50 deletions, 0 additions, one commit. No prose touched, no ceiling changed, no other package. The ratchet red → green pair in the PR body is the gate's own documented behaviour (#4690) and the --self-test 64/64 stands.

Landing form: draft; first line Fixes #14304 — correct: the round-1 ACCEPT ledger named the eval stub as this card's only deferral, so the merge closes the card. Labels documentation, size/s, skip-changeset (no contract claim ⇒ no needs:contract-review, correctly). Ruling quoted (#14296 item 2 = A).

CI at 5631fd8a: green — Lint & Repo Gates success (12:46Z), Type Check ×5, Test Core 1–6, Governed Surface Queue Guard, the single-writer / same-issue / Part-of guards, Spec property liveness, doc links, PR size, Check Changeset all success.

Next. Reviewers os-zhuang + hotlong requested with draft: true; the merge is the maintainer's. At merge the card closes by Fixes; the seat strips pm:dispatched afterwards.

Generated by Claude Code

Round 2 MERGED — PR #14564 @ 5631fd8a landed on main as 35383c41a (merge queue commit 12:53:20Z, merged_at 2026-09-02T13:17:58Z, merged by os-zhuang), and this card was closed by that merge at 13:17:59Z. Session: session_01LraLgQVGq8egUwfYZpbYt1

pm:dispatched stripped now (labels after: documentation · priority:p1 · domain:skills), read back after the write.
Verified on origin/main at 00:58Z 09-03, not from the PR page alone: git log --grep '#14564' returns the commit, and git ls-tree origin/main -- skills/objectstack-api/evals/README.md returns nothing — the stub is gone.
⚠️ Seat bookkeeping correction, recorded plainly: the seat's merge patrols kept this PR listed "at the governed terminal, awaiting the maintainer" from 13:17Z until this reading at 00:58Z 09-03 — about eleven and a half hours after the merge. The patrol window was reading recent merge commits and did not reach back to this one; the seat post ([PM seat] domain:skills — 🟢 os-elon-musk · 由 os-elon-musk 账户的项目负责 #7623) and the [Decision] Skills optimization program — batch 1 (4 items): new-file ceilings for splits · planned-eval stubs · react-blocks double rendering · published pm-dispatch scope #14296 ledger are corrected in this round. Nothing on the card was blocked by the delay (the card had already closed), but the decision batch's close was late by the same interval.
Nothing deferred remains on this card: round 1 (PR skills(api): optimization flight — RestApiEndpointSchema example and other packages' anchors cut, the apiMethods rule stated once, http.server mount / error ledger / OCC taught (net −1,676 tokens) #14448) implemented every DELETE / MERGE / REWRITE finding and the three funded additions; round 2 executed API-H-01 under [Decision] Skills optimization program — batch 1 (4 items): new-file ceilings for splits · planned-eval stubs · react-blocks double rendering · published pm-dispatch scope #14296 item 2 = A. API-F-06 was the one item routed to triage as an out-of-scope card rather than a doc edit, per the flight scope.

Generated by Claude Code

Navigation Menu

Repository navigation

Audit summary

Top findings

Three funded additions

Flight scope

Flight constraints (binding)

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

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

Real-usage corpus (what was grepped)

Findings

Totals

Incidental falsehoods

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Description

Audit summary

Top findings

Three funded additions

Flight scope

Flight constraints (binding)

Activity

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

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

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

Real-usage corpus (what was grepped)

Findings

Totals

Incidental falsehoods

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 2, 2026

os-litant commented on Sep 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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

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