Skip to content

CXF-274: narrow the skills' prose to what the code actually requires #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
manuel-ts-14 wants to merge 2 commits into
base: main
Choose a base branch
from
+18 −0
Open

CXF-274: narrow the skills' prose to what the code actually requires #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c30ecc0
CXF-274: type the source-openapi-spec Output Contract to match the sc…
manuel-ts-14 Sep 11, 2026
0d3979d
CXF-274: name the Grant type and provisioning nesting in write-connec…
manuel-ts-14 Sep 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions skills/source-openapi-spec/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,19 @@ is trimmed by selection, never by editing the vendored document.
Emit the `sourcing` and `park_evidence` halves of the pre1.json artifact:

- `sourcing`: `{spec_url, fetched_at, authority_rung, spec_bytes}`.
- `spec_url` (string) and `fetched_at` (string, ISO-8601).
- `authority_rung` (string, NOT a number) - the ladder rung as a string,
e.g. `"1"` for an official published spec.
Comment on lines +62 to +63

@github-actions github-actions Bot Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: the string-not-number typing is right (stages.ts:489 uses nonEmptyString), but the example value "1" diverges from the repo's own golden artifacts, which all use the descriptive rung name — "official published spec at a stable URL" in evals/runner/drivers/tier0/canned-pre1-directory-proceed/pre1.json:26, score.test.ts:239, and stages.test.ts:307. Both forms pass P3, so nothing breaks, but a skill that is being written to match the scorer will now teach an encoding no fixture uses. Consider e.g. "official published spec at a stable URL" for rung 1 (or "1" — official published spec at a stable URL) so prose and fixtures agree. (confidence: high on the divergence, medium on which form you want as canonical)

- `spec_bytes` (integer) - from `wc -c`; above 0 and under 1048576.
- `park_evidence`: `{spec_version_checked, missing_paths, vendor_doc, revisit_trigger}`.
- `spec_version_checked` (string) - the provider's bare version value and
nothing else, e.g. `"1.2.0"`. Not a sentence, and not a composite carrying
hashes, byte counts, or fetch timestamps; those belong in `sourcing`.
- `missing_paths` (array of strings) - the literal OpenAPI path templates
that are absent, e.g. `["/v1/users", "/v1/groups",
"/v1/groups/{groupId}/members"]`. Not prose descriptions of the missing
capability families.
- `vendor_doc` (string) and `revisit_trigger` (string), both non-empty.
Comment on lines +69 to +73

@github-actions github-actions Bot Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: P4 also rejects an empty missing_paths array (stages.ts:511, asserted by stages.test.ts:459 "P4 fails when missing_paths is empty"), and every element must be a non-empty string. The new prose spells out "both non-empty" for vendor_doc/revisit_trigger but leaves missing_paths as just "array of strings", so the one array-shaped gate is the one requirement still undocumented — evals/README.md:134 already states it. Suggest "(array of at least one non-empty string)". (confidence: high)


## Exit criteria

Expand Down
6 changes: 6 additions & 0 deletions skills/write-connector-source/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@ rule: when the served guide conflicts with any other doc, the served guide wins.
3. Slot identity is by JS reference - never re-call `slot()`.
4. The bundle targets ES5 - no `u` regex flag; goja quirks apply.
5. Import only from `@baton/runtime`, `@baton/types`, `@baton/helpers` (`@baton/*` resolution).
6. Provisioning: emit `provisioningResponse.grant({grants: [...]})` / `.revoke({})`;
that `Grant` is `@baton/types`' (NO `"@type"`), not the proto-shaped `sdk-types`
one. Attach the walkers under `provisioning: {grant, revoke}` - the runtime-facing
`RuntimeResourceTypeSpec` carries only that nesting.
Comment on lines +32 to +33

@github-actions github-actions Bot Sep 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Suggestion: the RuntimeResourceTypeSpec citation isn't the type an author's code is checked against. ConnectorSpec.resourceTypes is readonly AuthoredResourceTypeSpec[] (baton/runtime.d.ts:1954), and AuthoredResourceTypeSpec (1934-1942) carries top-level grant/revoke and nested provisioning — same as ResourceTypeSpecShape (2050-2058). RuntimeResourceTypeSpec (1724) is declared but referenced nowhere in the authoring surface, so it can't be what makes the flat form wrong. Consider either dropping the rationale clause and stating the nesting as the required spelling outright, or replacing it with whatever actually rejects the flat form at build/register time — otherwise an agent that reads runtime.d.ts and finds the flat form on the authored type has a directly contradicting signal. (Medium confidence: the nesting guidance itself may well be correct; only the stated justification doesn't hold.)


Worked skeletons: `examples/http/connector.ts` (transport + offset
pagination + users/groups/membership grants), `examples/static/connector.ts` (zero-config), and the lifecycle doc's Okta worked example (pin in SOURCES.md).
Expand Down Expand Up @@ -183,6 +187,8 @@ Taught as contract rules, not eval-gaming literals:
- WithExternalID is DEPRECATED - never required.
- Do not write plaintext secrets into `connector.ts`.
- Do not claim the build schema-validates `capabilities.json`.
- Do not put a proto-JSON `"@type"` in a `provisioningResponse.grant` grant -
that `Grant` has no discriminator.

## Blocker protocol

Expand Down
Loading