Adapter-onboarding skill — generator for the provider tail

[kyle-sexton]

Parent

Refs #2933. Source: topic pocock-shipping-breakdown (PR backfilled when opened). Locked direction: HYBRID shipping model — bundled hardened adapters for the majors, this skill for the tail.

What to build

A skill that helps a CONSUMER generate a work-item-tracker adapter for a provider we don't bundle, via interview + live exploration of their actual tracker instance (the jira adapter's history is the proof: per-instance semantics like done-state categories and blocker-link types could only be settled by inspecting the real instance). Shape constraints from the interview:

• Deterministic parts scripted (/discipline:script-the-deterministic-work); reasoning (semantic mapping, interview) stays outside scripts
• Security posture is template-driven, not re-derived: the generator bakes in the jira-grade guards (token via env-name indirection never argv, host validation, deny-by-default egress) as the starting skeleton
• Verification: generated adapter must pass the existing conformance suite (the skill also generates the bindings/<name>.sh conformance binding) — plus the normalization-fidelity check being added under the contract-hygiene item
• Generated adapters land in the consumer's repo (consumer-local adapter dir), owned by their review/CI; the contract-version handshake protects against silent skew as the core evolves
• Honest capability manifests: verbs the provider can't support are capability-gated, never faked

Acceptance criteria

• Skill exists with interview + live-exploration + generate + conformance-verify flow
• Security skeleton templates match or exceed jira-adapter guards
• A generated adapter passing conformance is demonstrated end-to-end (Gitea/Forgejo item is the designated dogfood)

Blocked by

• Seam: contract hygiene — dangling ADR 0022, version handshake, label-default SSOT #2942 (contract-version handshake + normalization-fidelity check are prerequisites)

[kyle-sexton]

Status: built, with the third criterion blocked

Landed on claude/pocock-shipping-breakdown-ukohlx (6dd2ad25, refined by 8a5a8950).

Against the acceptance criteria

• Skill exists with interview + live-exploration + generate + conformance-verify flow.
  /work-items:onboard-adapter. Judgement stays in the skill (which verbs a provider can honestly
  support, what its fields mean, what a live instance returns); the deterministic half is
  scripts/generate-adapter.sh, and the adapter spec is the whole handoff between them.
• Security skeleton templates match or exceed the jira-adapter guards. Matched: credential
  read from the env var named by the binding and passed to curl through a stdin config so it
  never reaches argv; bare-hostname validation; deny-by-default egress; anchored allowlists on
  every value reaching a request path. Exceeded in three places: --proto '=https' so HTTPS is
  enforced by curl rather than by the URL string; redirects not followed, so the Authorization
  header cannot be replayed to an unauthorized host; and a binding-side host_suffix pin, which
  jira has no equivalent of.
  This is executable rather than asserted — the generator emits a common.test.sh that is real
  and passing at generation time (58 cases), including that the credential is absent from argv
  and present in the stdin config.
• A generated adapter passing conformance demonstrated end-to-end. Blocked — see below.

What is blocked, precisely

No Gitea/Forgejo instance is reachable from this environment, so the abstract conformance suite
has not been run against a live provider. What has run, offline and in CI: the generated guards,
the manifest and manifest-versus-filesystem checks, and a mocked-transport suite per implemented
verb of the #2952 dogfood adapter. The binding at conformance/bindings/gitea.sh is written and
refuses to run without an explicitly named throwaway target.

Unblocks: a throwaway Gitea/Forgejo instance, and
WIT_CONFORMANCE_GITEA_HOST / WIT_CONFORMANCE_GITEA_SCOPE / a token pointed at it. I have not
closed this issue, because closing it would assert a criterion that has not been met.

Findings from the #2952 dogfood, fixed in the generator

The dogfood run found four real defects, which is what it was for:

1. A consumer-local adapter could not resolve the seam libraries at all unless the consumer had
   vendored the whole seam — which defeats the purpose, since the adapter lands in the consumer's
   repo while the engine stays in the read-only plugin directory. The dispatcher now exports
   WIT_SEAM_LIB_DIR.
2. A generated conformance binding was unreachable by the runner, which only looked in its own
   bundled bindings/. It now resolves the same two-root way adapters do. The binding name is also
   constrained before it is interpolated into a path.
3. limits had no way to say "no ceiling". Gitea rejects only duplicate and circular
   dependency edges and caps nothing, and 0 already means "unsupported" — so a ceiling-free
   provider had to invent a plausible number that callers would then branch on. null is now a
   third documented value.
4. A substitution value carrying a placeholder reached generated output verbatim — the
   self-hosted host-pin sentence shipped reading the raw DISPLAY_NAME placeholder, because the
   renderer walks its key list once and never revisits a value inserted by a later key. Fixed, with
   a regression case that greps every generated file under both host postures.

Two gaps closed while there: generated adapters now ship a capabilities.test.sh whose
load-bearing case is that the manifest agrees with the filesystem (a verb declared true with
no script behind it, or a script left behind for a verb since set to false, appears in no other
test); and an explicitly empty --out-root is now a usage error rather than silently falling back
to the repo root.

---

Generated by Claude Code