skills(automation): integrations are declared, not coded — rule section, per-archetype recipes, three evals

.changeset/27223-integrations-declared.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/skills": patch
+---
+
+Clause-②: no
+Metadata-protocol: none
+
+objectstack-automation: integrations are declared, not coded. The `connector_action`
+node row no longer calls a connector "pre-built"; a new SKILL.md section states the
+declarative-connector-first rule (a vendor system over HTTP is a `connectors:` entry
+with `provider: 'openapi' | 'mcp' | 'rest'`, a packaged spec and `auth.credentialRef`,
+dispatched by `connector_action`; a vendor callback is an `api` flow), the five cases
+that justify platform code, and that a document the loader cannot take yet is a gap to
+name — never a reason to write a plugin. `references/integration-recipes.md` carries one
+recipe per archetype with the author / administrator credential hand-off and today's
+limits (`connectorConfig.input` is sent as written; no `oauth2`; no vendor-signed
+callbacks). `evals/integrations-declared.json` adds the DocuSign, Stripe-read and
+vendor-without-spec cases; the DocuSign case fails any answer that proposes a plugin.

scripts/check-skills-token-ratchet.mjs

@@ -441,7 +441,26 @@ export const CEILINGS = new Map([
   // AT the measurement. Maintainer ruling 2026-10-27 on the seat's decision
   // card 「skills 修复卡的教学和 eval 都撞 token 天花板,怎么付?」, tap A
   // verbatim and untranslated: 「A:先削重复,余额按实测提高」.
-  ['skills/objectstack-automation/SKILL.md', 6466],
+  // 6466 -> 6465 (card #27223): the `connector_action` row no longer says
+  // "pre-built", the "reserve custom code for edge-case integrations" line is
+  // gone, and a new section "Integrations are declared, not coded" states the
+  // declarative-connector-first rule, the five cases that justify platform
+  // code and the gap-naming discipline. Paid down in the same file: the `http`
+  // row's auth-routing tail (now in references/integration-recipes.md), the
+  // Flow Variables example re-spelled one entry per line, a stale "(see the
+  // approval example below)" pointer, the ADR-0032 sentence and the eval
+  // pointer in References, and eight clause-level trims. Arithmetic in priced
+  // bytes (stamp line excluded): 25864 -> 25860 (-4 net) -> ceil(25860 / 4) =
+  // 6465; re-locked AT the measurement, headroom 0 tokens.
+  // 6465 -> 6457 (same card, contract-review patch round): the five-condition
+  // sentence gains "and then it is the platform's, filed as a card; the app
+  // still writes none" (ADR-0019 D2), and the flow-type table's `api` row names
+  // `secretRef` (or a literal `secret`) instead of `secret` alone. Paid down in
+  // the same file: the CEL blockquote's "(the example apps use plain strings)",
+  // three pointer lines' "Moved to", and five clause-level trims. Arithmetic in
+  // priced bytes: 25860 -> 25827 (-33 net) -> ceil(25827 / 4) = 6457; re-locked
+  // AT the measurement, headroom 0 tokens.
+  ['skills/objectstack-automation/SKILL.md', 6457],
   // 13783 -> 13892 (2026-08-31 app-repo-principles raise, see the block above).
   // The invariant-vs-transition-gate choice, placed in the field-conditional-rule
   // bullet list where the tool is actually picked. Both wrong picks are silent:
@@ -727,6 +746,14 @@ export const CEILINGS = new Map([
 
   // objectstack-automation
   ['skills/objectstack-automation/evals/approvals/test-revise-loop.md', 1329],
+  // NEW FILE (card #27223): the three integration cases — DocuSign (fails any
+  // answer proposing a platform plugin), Stripe read, vendor without a spec.
+  // Pinned AT its landed count, no headroom. Re-measured in the same PR's
+  // contract-review patch round (`clientSecret` -> `clientSecret:` in case 1's
+  // must_not_contain, so a correct answer naming the absent field still passes):
+  // 4772 -> 4773 bytes, 1193 -> 1194.
+  //   ceil($(wc -c < skills/objectstack-automation/evals/integrations-declared.json) / 4) == ceil(4773 / 4)
+  ['skills/objectstack-automation/evals/integrations-declared.json', 1194],
 
   // objectstack-ui — the three authored eval files; its `references/react-blocks.md`
   // is generator-owned and carries no row here on purpose (see the boundary
@@ -1077,6 +1104,18 @@ export const CEILINGS = new Map([
   // because a split that arrives with budget is a raise wearing a new path.
   // The package deltas are the pointer lines and the four new file titles only.
   ['skills/objectstack-automation/references/examples-flows.md', 1436],
+  // NEW FILE (card #27223): one recipe per integration archetype — OpenAPI with
+  // a static key, remote MCP with a static header, plain REST, the vendor
+  // callback, a hand-written document for a spec-less vendor — plus the two
+  // "not yet" entries (OAuth, request signing) and the author / administrator
+  // credential hand-off. Pinned AT its landed count, no headroom. Re-measured
+  // in the same PR's contract-review patch round: recipe 1's `$ref` wording
+  // widened from "no `$ref` into other files" to "dereference every `$ref`
+  // offline, in-document ones included" (the loader skips a `$ref` parameter,
+  // request body or response, so the derived schema silently loses it):
+  // 8705 -> 8814 bytes, 2177 -> 2204.
+  //   ceil($(wc -c < skills/objectstack-automation/references/integration-recipes.md) / 4) == ceil(8814 / 4)
+  ['skills/objectstack-automation/references/integration-recipes.md', 2204],
   // 5569 -> 5587 (card #26298, audit #26184 row A2): the approval config table
   // gains `excludeSubmitter` (refused beside `onEmptyApprovers: 'auto_approve'`),
   // +105 tokens. Paid down first: Best Practices 1 and 4 restated the Branching