You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
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.
Closing: descoped on the live-conformance criterion
Maintainer scope call — "I don't think we need it, we just need linear." Closing on what shipped rather than leaving this open indefinitely against a criterion we've decided not to pursue.
Gitea stays shipped and supported. The adapter merged in #3056 and remains the free, self-hostable option serving the no-paid-tool constraint this effort set for solo developers. What's descoped is validating it against a live server, not the adapter itself.
Against the acceptance criteria, stated honestly
Adapter generated (not hand-written) via the onboarding skill — generated through /work-items:onboard-adapter as the designated dogfood.
Honest capability gating — add-sub-item, list-sub-items, claim, reclaim, renew-lease all declared false with sub_item_depth: 0, because Gitea has neither sub-issues nor a lease surface. No verb script exists for any false verb — the contract's declared-false-exits-6 gate handles them, so nothing is stubbed or faked to look supported.
Passing conformance — not met, descoped.
Generator findings from the run filed back — met in substance, and better than filing: four findings were found and fixed in the generator and its templates rather than deferred. A hardcoded sample id number (12) that would have failed on day one for any consumer with a different api.sample_id; a basic-auth auth_user baked to a placeholder with no override; the host_suffix domain-boundary bypass fixed in the shared template so every future generated adapter inherits it; and a quote_safe choke point the jira adapter never had.
Setup skill's provider comparison updated — verified present in skills/setup/SKILL.md and skills/setup/reference/providers.md.
Correcting the blocker reason on record
Earlier notes on this effort — including the adapter README — said no Gitea instance was reachable from the build environment. That was an untested assumption stated as fact, and it is false. Gitea ships as a single self-contained binary with sqlite built in, its releases are fetchable from that environment, and a real Gitea 1.22.6 was downloaded and version-verified there.
The actual blocker is narrower: serving it needs privileged setup — a dedicated unprivileged user plus cap_net_bind_service, since Gitea declines to run as root — which the sandbox's permission policy gates. Reachability was never the constraint. Corrected in adapters/gitea/README.md and in the SSOT.
Do not "unblock" this later by relaxing the host rule
Port 443 and TLS are structural, not preferences: wit_gitea_http builds https://<host>/api/v1 under --proto '=https', and config.gitea.host must be a bare hostname, so a high port is not expressible. That rule exists so a PR-modifiable binding cannot smuggle URL structure and redirect the credential off the intended tenant. Widening it to make a suite run would trade a real security control for a green check.
If a live pass is ever wanted: stand up a throwaway Gitea on 443 with TLS, set WIT_CONFORMANCE_GITEA_HOST / WIT_CONFORMANCE_GITEA_SCOPE / WIT_GITEA_TOKEN, and run conformance/run-conformance.sh --binding gitea. The binding is written and refuses to run without an explicitly named throwaway target.
Full reasoning recorded durably in docs/upstream/aihero-shipping-course.md § "Adapter-track scope decision".
Activity
docs(planning): Pocock Shipping-section absorption — interview contra…
feat(work-items): gitea/forgejo adapter, generated as the onboarding …
kyle-sexton commentedon Aug 20, 2026
Status: adapter generated and offline-verified; live conformance blocked
Landed on
claude/pocock-shipping-breakdown-ukohlx(8a5a8950).Against the acceptance criteria
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 fromadapters/gitea/adapter-spec.json; only theper-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.
two gaps, recorded on #2950
and all fixed in the generator.
giteais now a listed provider with its ownrow; the full comparison moved to
skills/setup/reference/providers.md(the skill had reachedits 500-line hard cap).
Capability honesty
Gated to exit
6, each for a stated reason rather than for convenience:add-sub-item,list-sub-itemsIssuehas no parent field at all (modules/structs/issue.go). Structurally absent, not unmapped.claim,renew-lease,reclaimConsequence stated plainly rather than buried:
/work-items:workcannot claim ongitea, so it isnot 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)
pull_requestpopulated).list-itemsdrops them — a PR arrivingas a work item would be selected and worked like one.
create-itemtakes label IDs, not names (CreateIssueOption.labelsis[]int64). Theadapter 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_countis N+1. TheIssuecarries no dependency data and there is no bulkendpoint. Returning
0would be worse than slow —list-frontierfilters onblocked_by_count == 0, so every blocked item would surface as available work.POST /issues/{index}/dependenciesmakes the URL issue depend onthe body issue. The sibling
/blocksendpoint is the same edge from the other end; using itwould invert every edge, and the frontier would release exactly the items it should hold.
ALLOW_CROSS_REPOSITORY_DEPENDENCIESdefaultstrue and can be disabled, answering
400 CrossRepositoryDependencies not enabled; mapped to exit7with the setting named.forced
limitsto grow anullvalue.Blocker
No Gitea or Forgejo instance is reachable from this environment.
conformance/bindings/gitea.shiswritten and refuses to run without an explicitly named throwaway target
(
WIT_CONFORMANCE_GITEA_HOST+WIT_CONFORMANCE_GITEA_SCOPE), so a destructive suite cannot fallback 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
fix(work-items): refuse quote-breaking spec values, and record the ex…
fix(work-items): regenerate the catalog and classify onboard-adapter …
fix(work-items): make the host pin a domain boundary, and test the di…
fix(work-items,skill-quality): cover the host pin everywhere it lande…
fix: set the exec bit on disk, and stop reading an old ShellCheck as …
fix(work-items): paginate the linear activity check, and stop templat…
fix(work-items): clear the four remaining review findings, and a late…
fix(work-items): clear the ShellCheck findings my own commits introduced
feat: adapter track (onboarding generator, gitea/forgejo, linear) + L…
kyle-sexton commentedon Aug 21, 2026
Closing: descoped on the live-conformance criterion
Maintainer scope call — "I don't think we need it, we just need linear." Closing on what shipped rather than leaving this open indefinitely against a criterion we've decided not to pursue.
Gitea stays shipped and supported. The adapter merged in #3056 and remains the free, self-hostable option serving the no-paid-tool constraint this effort set for solo developers. What's descoped is validating it against a live server, not the adapter itself.
Against the acceptance criteria, stated honestly
/work-items:onboard-adapteras the designated dogfood.add-sub-item,list-sub-items,claim,reclaim,renew-leaseall declaredfalsewithsub_item_depth: 0, because Gitea has neither sub-issues nor a lease surface. No verb script exists for anyfalseverb — the contract's declared-false-exits-6gate handles them, so nothing is stubbed or faked to look supported.12) that would have failed on day one for any consumer with a differentapi.sample_id; a basic-authauth_userbaked to a placeholder with no override; thehost_suffixdomain-boundary bypass fixed in the shared template so every future generated adapter inherits it; and aquote_safechoke point the jira adapter never had.skills/setup/SKILL.mdandskills/setup/reference/providers.md.Correcting the blocker reason on record
Earlier notes on this effort — including the adapter README — said no Gitea instance was reachable from the build environment. That was an untested assumption stated as fact, and it is false. Gitea ships as a single self-contained binary with sqlite built in, its releases are fetchable from that environment, and a real Gitea 1.22.6 was downloaded and version-verified there.
The actual blocker is narrower: serving it needs privileged setup — a dedicated unprivileged user plus
cap_net_bind_service, since Gitea declines to run as root — which the sandbox's permission policy gates. Reachability was never the constraint. Corrected inadapters/gitea/README.mdand in the SSOT.Do not "unblock" this later by relaxing the host rule
Port 443 and TLS are structural, not preferences:
wit_gitea_httpbuildshttps://<host>/api/v1under--proto '=https', andconfig.gitea.hostmust be a bare hostname, so a high port is not expressible. That rule exists so a PR-modifiable binding cannot smuggle URL structure and redirect the credential off the intended tenant. Widening it to make a suite run would trade a real security control for a green check.If a live pass is ever wanted: stand up a throwaway Gitea on 443 with TLS, set
WIT_CONFORMANCE_GITEA_HOST/WIT_CONFORMANCE_GITEA_SCOPE/WIT_GITEA_TOKEN, and runconformance/run-conformance.sh --binding gitea. The binding is written and refuses to run without an explicitly named throwaway target.Full reasoning recorded durably in
docs/upstream/aihero-shipping-course.md§ "Adapter-track scope decision".Generated by Claude Code
docs(upstream): record the adapter-track scope decision and correct t…