Gitea/Forgejo adapter — generator dogfood candidate

[kyle-sexton]

Parent

Refs #2933. Source: topic pocock-shipping-breakdown (PR backfilled when opened).

What to build

An adapter for Gitea/Forgejo (free, self-hostable, GitHub-shaped API) — deliberately built AS the first dogfood of the adapter-onboarding skill rather than hand-written: run the generator against a live Gitea/Forgejo instance, let it interview + explore + generate + conformance-verify, and treat every gap it hits as a finding against the generator. Serves the no-paid-tool constraint for solo devs and validates the hybrid shipping model end-to-end. Capability honesty required where the API diverges from GitHub (native sub-issues/dependencies differ by version — gate, don't fake).

Acceptance criteria

• Adapter generated (not hand-written) via the onboarding skill, passing conformance with honest capability gating
• Generator findings from the run filed back against the onboarding skill
• Setup skill's provider comparison updated

Blocked by

• Adapter-onboarding skill — generator for the provider tail #2950 (the onboarding skill is the point)

[kyle-sexton]

Status: adapter generated and offline-verified; live conformance blocked

Landed on claude/pocock-shipping-breakdown-ukohlx (8a5a8950).

Against the acceptance criteria

• [~] Adapter generated (not hand-written) via the onboarding skill, passing conformance with
  honest capability gating. Generated — the scaffolds, security skeleton, manifest, conformance
  binding, and both generated test suites all came out of
  /work-items:onboard-adapter's generator from adapters/gitea/adapter-spec.json; only the
  per-verb provider mappings were written by hand, which is the split the skill is built around.
  Capability gating is honest (below). Conformance against a live instance has NOT been run —
  see the blocker.
• Generator findings from the run filed back against the onboarding skill. Four defects and
  two gaps, recorded on #2950
  and all fixed in the generator.
• Setup skill's provider comparison updated. gitea is now a listed provider with its own
  row; the full comparison moved to skills/setup/reference/providers.md (the skill had reached
  its 500-line hard cap).

Capability honesty

Gated to exit 6, each for a stated reason rather than for convenience:

Gated	Why
add-sub-item, list-sub-items	Gitea's Issue has no parent field at all (modules/structs/issue.go). Structurally absent, not unmapped.
claim, renew-lease, reclaim	Gitea has the primitives the github lease is built from (assignees + comments), but whether concurrent assignment is arbitrated cannot be settled without a live instance and two identities. An emulated lease over last-write-wins loses races silently — worse than not having one.

Consequence stated plainly rather than buried: /work-items:work cannot claim on gitea, so it is
not a multi-agent coordination surface today. Enabling leases later is a manifest change plus three
verb scripts; nothing else in the adapter assumes their absence.

Divergences found (verified against the Gitea source, not assumed from GitHub's API)

• A pull request IS an issue (pull_request populated). list-items drops them — a PR arriving
  as a work item would be selected and worked like one.
• create-item takes label IDs, not names (CreateIssueOption.labels is []int64). The
  adapter resolves names against the repo's label set and refuses an unknown name rather than
  dropping it: an item filed without its type or priority label is invisible to the very selection
  tiers that would have picked it up.
• blocked_by_count is N+1. The Issue carries no dependency data and there is no bulk
  endpoint. Returning 0 would be worse than slow — list-frontier filters on
  blocked_by_count == 0, so every blocked item would surface as available work.
• Dependency direction: POST /issues/{index}/dependencies makes the URL issue depend on
  the body issue. The sibling /blocks endpoint is the same edge from the other end; using it
  would invert every edge, and the frontier would release exactly the items it should hold.
• Cross-repo edges work but are instance-gated. ALLOW_CROSS_REPOSITORY_DEPENDENCIES defaults
  true and can be disabled, answering 400 CrossRepositoryDependencies not enabled; mapped to exit
  7 with the setting named.
• No ceiling on dependencies — Gitea rejects only duplicate and circular edges. This is what
  forced limits to grow a null value.

Blocker

No Gitea or Forgejo instance is reachable from this environment. conformance/bindings/gitea.sh is
written and refuses to run without an explicitly named throwaway target
(WIT_CONFORMANCE_GITEA_HOST + WIT_CONFORMANCE_GITEA_SCOPE), so a destructive suite cannot fall
back to a default. Until that pass happens, treat the live behaviour as
documented-and-tested-against-the-documentation, not as verified — and Forgejo parity as assumed
rather than measured.

Left open for that reason.

---

Generated by Claude Code