@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

package/docs/external/provider-capability-manifests.md

@@ -0,0 +1,204 @@
+# Provider capability manifests
+
+## Purpose
+
+Provider manifests make external backend support data-driven. Each adapter declares supported interfaces, operations, auth modes, webhook events, rate-limit model, object identity fields, and unsupported features. Kradle uses the manifest to render UI, validate CRDs, run contract tests, and disable unsupported actions.
+
+## Manifest schema
+
+```yaml
+apiVersion: kradle.a5c.ai/v1alpha1
+kind: ExternalProviderCapabilityManifest
+metadata:
+  name: github-v1
+spec:
+  providerType: github
+  displayName: GitHub
+  hosting:
+    - saas
+    - github-enterprise-server
+  authModes:
+    - github-app
+    - oauth-user
+  api:
+    rest: true
+    graphql: true
+    webhook: true
+  identity:
+    nativeIdFields: [id, number]
+    globalIdField: node_id
+    urlField: html_url
+    versionFields: [etag, updated_at, head_sha]
+  interfaces: {}
+```
+
+## Operation shape
+
+```yaml
+operation: createPullRequest
+supported: true
+write: true
+requires:
+  permissions:
+    - gitForge.pullRequests.write
+  authModes:
+    - github-app
+    - oauth-user
+  nativeScopes:
+    - pull_requests:write
+idempotency:
+  mode: synthetic-key
+rateLimitCost:
+  restRequests: 1
+webhookConfirmation:
+  events: [pull_request]
+```
+
+## GitHub manifest sketch
+
+```yaml
+providerType: github
+interfaces:
+  issueTracking:
+    supported: true
+    objects: [Issue, IssueComment, Label, Milestone]
+    operations:
+      - listIssues
+      - getIssue
+      - createIssue
+      - updateIssue
+      - closeIssue
+      - listComments
+      - createComment
+      - updateComment
+      - listLabels
+      - syncLabels
+    webhooks: [issues, issue_comment, label, milestone]
+  cicd:
+    supported: true
+    objects: [WorkflowRun, WorkflowJob, CheckRun, CheckSuite, CommitStatus, Runner]
+    operations:
+      - listWorkflowRuns
+      - getWorkflowRun
+      - listWorkflowJobs
+      - rerunWorkflowRun
+      - cancelWorkflowRun
+      - listSelfHostedRunners
+      - createCheckRun
+      - updateCheckRun
+    webhooks: [workflow_run, workflow_job, check_run, check_suite, status]
+  gitForge:
+    supported: true
+    objects: [Repository, PullRequest, Review, Ref, Commit, DeployKey, BranchProtection, Collaborator]
+    operations:
+      - listRepositories
+      - getRepository
+      - createRepository
+      - updateRepository
+      - listPullRequests
+      - createPullRequest
+      - updatePullRequest
+      - mergePullRequest
+      - listRefs
+      - getCommit
+      - syncDeployKeys
+      - syncBranchProtection
+    webhooks: [repository, pull_request, pull_request_review, pull_request_review_comment, push, create, delete, deploy_key, branch_protection_rule]
+```
+
+## GitLab manifest sketch
+
+```yaml
+providerType: gitlab
+hosting: [saas, self-managed]
+authModes: [oauth-user, project-token, group-token, personal-access-token]
+interfaces:
+  issueTracking:
+    supported: true
+    objects: [Issue, Note, Label, Milestone]
+    webhooks: [Issues Hook, Note Hook]
+  cicd:
+    supported: true
+    objects: [Pipeline, Job, Artifact, Runner]
+    webhooks: [Pipeline Hook, Job Hook]
+  gitForge:
+    supported: true
+    objects: [Project, MergeRequest, Approval, Branch, Tag, DeployKey, ProtectedBranch]
+    webhooks: [Push Hook, Tag Push Hook, Merge Request Hook]
+```
+
+## Jira manifest sketch
+
+```yaml
+providerType: jira
+hosting: [cloud, data-center]
+interfaces:
+  issueTracking:
+    supported: true
+    objects: [Issue, Comment, Project, Component, Version, Sprint, Board]
+    operations: [listIssues, getIssue, createIssue, updateIssue, transitionIssue, createComment, updateComment]
+    webhooks: [issue_created, issue_updated, issue_deleted, comment_created, comment_updated]
+  cicd:
+    supported: false
+  gitForge:
+    supported: false
+notes:
+  bodyFormat: atlassian-document-format
+```
+
+## Buildkite manifest sketch
+
+```yaml
+providerType: buildkite
+interfaces:
+  issueTracking:
+    supported: false
+  cicd:
+    supported: true
+    objects: [Pipeline, Build, Job, Agent, Artifact]
+    operations: [listPipelines, listBuilds, getBuild, listJobs, getLog, rebuildBuild, cancelBuild, listAgents]
+    webhooks: [build.scheduled, build.running, build.finished, job.finished]
+  gitForge:
+    supported: false
+```
+
+## Custom provider manifest
+
+Custom providers must declare exact operations and webhook normalization rules:
+
+```yaml
+providerType: custom
+adapterRef:
+  package: '@a5c-ai/kradle-provider-acme'
+  version: 1.x
+interfaces:
+  issueTracking:
+    supported: true
+    operations: [listIssues, getIssue]
+  cicd:
+    supported: false
+  gitForge:
+    supported: false
+```
+
+## UI use
+
+The UI uses manifests to:
+
+- show only supported interface checkboxes;
+- explain unsupported actions;
+- choose auth forms;
+- show webhook event requirements;
+- render provider-specific object labels;
+- warn when selected sync mode requires unsupported write operations;
+- drive setup wizard validation.
+
+## Test use
+
+Contract tests use manifests to:
+
+- generate provider capability tests;
+- assert unsupported operations are disabled;
+- run shared interface suites only for supported interfaces;
+- validate provider fixture completeness;
+- verify webhook event normalization coverage.

package/docs/external/provider-catalog.md

@@ -0,0 +1,139 @@
+# Pluggable backend provider catalog
+
+## Purpose
+
+This catalog lists likely external backend integrations and how each maps to Kradle's three unified interfaces:
+
+1. issue tracking;
+2. CI/CD;
+3. git forge.
+
+A backend can support one, two, or all three. Provider implementations should be capability-driven rather than hard-coded to GitHub semantics.
+
+## Provider matrix
+
+| Provider | Issue tracking | CI/CD | Git forge | Notes |
+| --- | --- | --- | --- | --- |
+| GitHub | yes | yes | yes | first full provider; GitHub Apps, REST, GraphQL, webhooks, Actions, Checks. |
+| GitLab | yes | yes | yes | issues, merge requests, pipelines/jobs, webhooks, project/group APIs; supports SaaS and self-managed. |
+| Bitbucket Cloud | limited/yes | yes | yes | repositories, pull requests, pipelines, webhooks; issue support depends on workspace/repo configuration. |
+| Bitbucket Data Center | limited/yes | external/limited | yes | repo/PR APIs and webhooks; CI often external Jenkins/Bamboo. |
+| Azure DevOps | yes | yes | yes | Work Items, Boards, Git repos/PRs, Pipelines, service hooks. |
+| Jira Cloud/Data Center | yes | no | no | work items/issues only; pairs well with GitHub/GitLab/Bitbucket or CI-only providers. |
+| Linear | yes | no | no | GraphQL issue/workflow model and webhooks; no native git forge. |
+| Buildkite | no | yes | no | builds, jobs, agents, artifacts, webhooks; pairs with GitHub/GitLab/Bitbucket. |
+| CircleCI | no | yes | no | pipelines, workflows, jobs, webhooks, artifacts; pairs with git forge providers. |
+| Jenkins | no | yes | no | jobs/builds/logs via remote API; webhook support usually plugin-specific. |
+| Gitea | yes | limited/external | yes | current internal/default forge path; can also be external-managed. |
+| Gerrit | no/limited | no | yes | code review and Git refs; often pairs with Jenkins/Buildkite. |
+| Raw Git server | no | no | partial | clone/fetch/push/refs only; no issue/PR semantics unless paired. |
+| Custom webhook backend | optional | optional | optional | provider adapter can normalize proprietary events into one interface. |
+
+## Provider profiles
+
+### Full forge providers
+
+Full forge providers typically implement all three interfaces:
+
+- GitHub;
+- GitLab;
+- Azure DevOps;
+- partially Bitbucket when issue and pipeline features are enabled.
+
+These providers can power repository pages end to end, but Kradle should still let each interface be enabled independently.
+
+### Work tracking providers
+
+Work tracking providers implement issue tracking only:
+
+- Jira;
+- Linear;
+- Azure Boards if used separately from Azure Repos/Pipelines;
+- custom ticket systems.
+
+Kradle maps these into issues/work items, labels, project fields, comments, assignees, and issue-triggered agent dispatch.
+
+### CI/CD providers
+
+CI/CD providers implement pipeline/job/run functionality only:
+
+- Buildkite;
+- CircleCI;
+- Jenkins;
+- Azure Pipelines if used separately;
+- GitHub Actions if GitHub forge is not used;
+- GitLab CI if GitLab forge is not used.
+
+Kradle maps these into `Pipeline`, `Job`, logs, artifacts, checks, runners, and triggers.
+
+### Git forge providers
+
+Git forge providers implement repos/PRs/refs/keys but may not own issues or CI:
+
+- GitHub;
+- GitLab;
+- Bitbucket;
+- Gitea;
+- Gerrit;
+- raw Git with limited semantics.
+
+Kradle maps these into repositories, pull requests/reviews, refs, commits, deploy keys, repository permissions, and branch protection.
+
+## Capability descriptor
+
+Each provider adapter should expose a descriptor:
+
+```yaml
+providerType: gitlab
+version: v1
+interfaces:
+  issueTracking:
+    supported: true
+    operations: [list, get, create, update, comment, label, transition]
+    webhookEvents: [issue, note]
+  cicd:
+    supported: true
+    operations: [listRuns, getRun, listJobs, getLog, retry, cancel]
+    webhookEvents: [pipeline, job]
+  gitForge:
+    supported: true
+    operations: [listRepos, getRepo, listPullRequests, createPullRequest, merge, listRefs]
+    webhookEvents: [push, mergeRequest, tagPush]
+authModes: [oauth-app, personal-token, project-token, self-managed-token]
+hosting: [saas, self-managed]
+rateLimitModel: provider-specific
+```
+
+## Provider-specific notes
+
+### GitLab
+
+GitLab should support issues, merge requests, pipelines/jobs, project/group webhooks, branches/tags, approvals, protected branches, deploy keys, and self-managed base URLs.
+
+### Bitbucket
+
+Bitbucket should separate Cloud and Data Center adapters because authentication, APIs, webhook payloads, and feature availability differ.
+
+### Jira
+
+Jira issue payloads use Atlassian Document Format for rich text in Cloud REST v3. Kradle needs a markdown/ADF conversion layer for issue body/comments.
+
+### Linear
+
+Linear is GraphQL-first and issue/workflow-oriented. It should support issue tracking with webhooks and a provider-specific field mapping for teams, cycles, projects, states, and labels.
+
+### Azure DevOps
+
+Azure DevOps can support all three interfaces, but Work Items, Git repos/PRs, Pipelines, and Service Hooks are separate service areas. Kradle should model them under one provider with separate interface credentials/scopes where needed.
+
+### Buildkite/CircleCI/Jenkins
+
+These are CI/CD-only providers. They should map to `Pipeline`/`Job` and can be paired with GitHub/GitLab/Bitbucket/Gitea for repo and PR context.
+
+## Acceptance criteria
+
+- Provider adapter selection is capability-driven.
+- A single Kradle repository can bind different providers per interface.
+- A provider can be self-managed with custom base URLs.
+- UI can explain unsupported operations before a user clicks them.
+- Tests can run provider contract suites against fake adapters for each interface.

package/docs/external/provider-rollout-testing.md

@@ -0,0 +1,78 @@
+# Provider rollout and testing
+
+## Purpose
+
+This document defines implementation slices and QA coverage for GitHub and future providers.
+
+## Rollout slices
+
+### Slice 1: provider registry and read-only GitHub binding
+
+- Add `ExternalBackendProvider`, `ExternalBackendBinding`, and sync policy resources.
+- Configure GitHub App Secret metadata.
+- Validate auth and installation access.
+- Show provider in org settings.
+
+### Slice 2: git forge read sync
+
+- Sync repositories and pull requests read-only.
+- Store external IDs and native URLs.
+- Show GitHub badges and links.
+- Backfill plus webhook convergence tests.
+
+### Slice 3: issue tracking sync
+
+- Sync issues, comments, labels, milestones.
+- Handle PR-backed issue identity.
+- Add issue write-through for authorized humans.
+
+### Slice 4: CI/CD sync
+
+- Sync workflow runs, jobs, checks, statuses.
+- Show GitHub Actions runs beside Kradle pipelines.
+- Add logs/artifacts lazy fetch.
+
+### Slice 5: write intents and conflicts
+
+- Add reviewed-write and write-through actions.
+- Add `ExternalWriteIntent` and `ExternalSyncConflict` UI.
+- Add agent write-back approval flow.
+
+### Slice 6: runner and advanced repo management
+
+- Self-hosted runner inventory/registration if enabled.
+- Deploy keys, collaborators, and branch protection sync.
+- Rate-limit aware bulk backfill.
+
+## Test coverage
+
+| Slice | Required tests |
+| --- | --- |
+| provider registry | auth Secret metadata, missing Secret, bad installation, no-token leak. |
+| git forge read | repo/PR backfill, webhook update, duplicate delivery, cross-org denial. |
+| issue sync | issue/comment/label update, PR-backed issue link, conflict. |
+| CI/CD sync | workflow/job/check event, rerun/cancel permission, log lazy fetch. |
+| write intents | approval required, provider write failure, confirmation, conflict. |
+| advanced repo | deploy key sync, branch protection drift, runner registration token no-leak. |
+
+## Fixtures
+
+Add fixtures for:
+
+- GitHub App provider Secret metadata;
+- installation binding;
+- repository webhook payloads;
+- issue/comment/label payloads;
+- pull request/review payloads;
+- workflow run/job/check payloads;
+- deploy key/branch protection payloads;
+- rate limit and abuse-limit responses;
+- redelivery payloads.
+
+## Acceptance criteria
+
+- GitHub can be enabled for one org/repository with selected interfaces.
+- A provider implementing only one interface can still be represented.
+- Webhook replay and backfill converge.
+- Bidirectional writes are explicit, permission-checked, and audited.
+- Future providers can be added by implementing one or more provider contracts.

package/docs/external/research-results.md

@@ -0,0 +1,48 @@
+# Research results
+
+## Purpose
+
+This document records the GitHub research used to design Kradle external backend integration. It intentionally focuses on official GitHub surfaces and the implications for Kradle's provider abstractions.
+
+## GitHub integration surfaces
+
+| Surface | Relevant GitHub capability | Kradle implication |
+| --- | --- | --- |
+| GitHub Apps | authenticate as app, installation, or user; installation tokens; permission-scoped access | use GitHub App installation as default automation identity; use user tokens only for actor-attributed actions. |
+| REST API | repositories, issues, pull requests, Actions, checks, webhooks, deploy keys, refs, commits | implement provider connectors with endpoint-specific permissions and rate-limit handling. |
+| GraphQL API | precise data selection, node IDs, connections/cursors | use for efficient list/detail sync, cross-object hydration, and stable global IDs. |
+| Webhooks | repository/org/app events with payloads and delivery IDs | use webhook-first sync for freshness and as trigger source. |
+| Webhook delivery APIs | recent delivery inspection and redelivery | support replay/recovery and delivery audit. |
+| Actions APIs | workflows, workflow runs, jobs, logs, self-hosted runners | map GitHub Actions into Kradle pipeline/job/runner abstractions. |
+| Checks/status APIs | checks, statuses, workflow check suites/runs | map external checks into Kradle CI status and PR gates. |
+| Deploy keys and Git access | repository-scoped SSH deploy keys and installation-token HTTP Git access | support external Git checkout/mirroring without PATs. |
+
+## Key findings
+
+- GitHub's REST API covers repository management, issue management, pull requests/reviews, workflow runs, self-hosted runners, checks, deploy keys, refs, commits, and repository webhooks.
+- GitHub webhooks should be subscribed narrowly; GitHub documents using secrets, HTTPS, event/action filtering, unique delivery IDs, fast 2XX responses, queues for asynchronous processing, and redelivery for recovery.
+- GitHub App installation tokens expire and are permission-bound; user access tokens can attribute user actions but are limited by both app permissions and user permissions.
+- GitHub GraphQL exposes precise object selection, node IDs, connections, and cursors; REST payloads often include `node_id`, which can bridge REST and GraphQL identities.
+- GitHub Actions workflow runs can be viewed, rerun, canceled, and logged through REST; self-hosted runners can be listed, registered, and deleted through Actions APIs.
+- GitHub pull requests are issue-like for labels, assignees, milestones, and comments, so issue and pull-request sync must coordinate shared issue-number identity.
+- GitHub deploy keys are repository-scoped SSH keys and are separate from GitHub App installation-token HTTP Git access.
+
+## Sources
+
+- GitHub REST API overview and repository endpoints.
+- GitHub Issues REST endpoints.
+- GitHub Pull Requests REST endpoints.
+- GitHub Actions workflow run, workflow, checks, and self-hosted runner endpoints.
+- GitHub Webhooks docs: events/payloads, best practices, validation, deliveries, redelivery.
+- GitHub Apps auth docs: app JWT, installation tokens, user tokens, permissions.
+- GitHub GraphQL docs: node IDs, precise queries, cursor pagination, schema.
+
+## Design impact
+
+Kradle should not create a GitHub-only data model. Instead, GitHub is the first provider implementation of three interfaces:
+
+1. issue tracking provider;
+2. CI/CD provider;
+3. git forge provider.
+
+GitHub can support all three. Other providers may only support one or two. For example, Jira may support issue tracking only; Buildkite may support CI/CD only; a raw Git server may support git forge only.

package/docs/external/security-auth-permissions.md

@@ -0,0 +1,81 @@
+# Security, auth, and permissions
+
+## Purpose
+
+External backend integration introduces provider tokens, webhooks, native permissions, and bidirectional writes. This document defines the security model.
+
+## Auth principles
+
+- Prefer GitHub Apps over PATs.
+- Store app IDs, private keys, webhook secrets, and client secrets in Kubernetes Secrets.
+- Never store provider access tokens in resource status.
+- Installation tokens are short-lived and cached in memory only when possible.
+- User-attributed writes require both Kradle authorization and provider user authorization.
+
+## Secret resources
+
+```yaml
+kind: Secret
+metadata:
+  name: github-app-a5c
+  namespace: kradle-org-a5c
+type: Opaque
+stringData:
+  app-id: "..."
+  private-key.pem: "..."
+  webhook-secret: "..."
+```
+
+`ExternalBackendProvider.spec.authRef` points to the Secret. UI displays only Secret name/key metadata.
+
+## Permission checks
+
+Every write requires:
+
+1. Kradle org/RBAC permission;
+2. provider binding allows interface and write mode;
+3. provider credentials have required native permission;
+4. actor attribution policy is satisfied;
+5. approval policy is satisfied for agents or high-risk writes;
+6. audit event is emitted.
+
+## Webhook security
+
+- Require HTTPS in production.
+- Validate provider signature before parsing payload.
+- Enforce replay/dedupe by delivery ID and timestamp where available.
+- Queue processing after quick 2XX response.
+- Store raw payloads only according to retention and redaction policy.
+- Avoid logging headers or payload fields containing secrets.
+
+## No-leak requirements
+
+Provider secrets and tokens must not appear in:
+
+- API responses;
+- resource status;
+- Kubernetes events;
+- sync events;
+- logs;
+- UI;
+- browser traces;
+- memory/context bundles;
+- test artifacts.
+
+## Agent interactions
+
+Agents may propose external writes, but Kradle owns approval and execution. Agent write-back to GitHub issues, PRs, checks, comments, labels, or branch updates must produce an `ExternalWriteIntent` and pass approval policy unless explicitly trusted.
+
+## Audit fields
+
+Audit external operations with:
+
+- org and namespace;
+- provider and binding;
+- interface;
+- actor and optional provider user;
+- native object ID/URL;
+- action;
+- write intent ID;
+- result;
+- digest of request/response with secrets removed.

package/docs/external/sync-state-machines.md

@@ -0,0 +1,108 @@
+# External sync state machines
+
+## Purpose
+
+This document defines stable phases and transitions for provider setup, bindings, webhook deliveries, backfill, write intents, conflicts, and provider health. UI, controllers, tests, and audit should use these phases consistently.
+
+## Provider phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Pending` | resource created, not yet validated. |
+| `Authenticating` | controller is checking credentials. |
+| `Discovering` | capabilities, installation, and rate-limit metadata are being discovered. |
+| `Ready` | provider can serve at least one enabled interface. |
+| `Degraded` | provider is usable but has warnings such as rate limits or partial interface failure. |
+| `Paused` | user paused sync/write operations. |
+| `Failed` | provider cannot be used until configuration changes. |
+
+## Binding phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Pending` | binding accepted. |
+| `ValidatingTarget` | target Kradle repo/project/org is being validated. |
+| `RegisteringWebhook` | provider webhook registration is in progress. |
+| `Backfilling` | initial sync is running. |
+| `Ready` | binding sync is active. |
+| `Conflict` | sync conflicts exist but binding may continue. |
+| `Paused` | sync paused for this binding. |
+| `Failed` | binding cannot sync. |
+
+## Webhook delivery phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Received` | request accepted. |
+| `SignatureRejected` | signature validation failed; no payload processing. |
+| `Queued` | valid delivery queued. |
+| `Normalizing` | provider payload is becoming canonical events. |
+| `Processing` | sync controller is applying events. |
+| `Succeeded` | event applied or safely deduped. |
+| `Retrying` | transient failure. |
+| `DeadLettered` | repeated failure needs operator action. |
+
+## Backfill phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Scheduled` | backfill requested. |
+| `Listing` | provider objects are being paginated. |
+| `Hydrating` | details are being fetched. |
+| `Applying` | Kradle projections are being updated. |
+| `Checkpointing` | cursor/high-watermark is being persisted. |
+| `Succeeded` | backfill completed. |
+| `RateLimited` | paused until reset. |
+| `Failed` | backfill failed. |
+
+## Write intent phases
+
+| Phase | Meaning |
+| --- | --- |
+| `PendingApproval` | approval required before provider call. |
+| `ReadyToSend` | admitted and queued for provider write. |
+| `Sending` | provider call in progress. |
+| `AwaitingConfirmation` | provider response accepted; waiting for webhook/read confirmation. |
+| `Succeeded` | provider state confirmed. |
+| `Conflict` | provider state changed or rejected due to version mismatch. |
+| `Retrying` | transient failure. |
+| `Rejected` | human or policy rejected the write. |
+| `Failed` | non-retryable failure. |
+
+## Conflict phases
+
+| Phase | Meaning |
+| --- | --- |
+| `Open` | conflict requires resolution. |
+| `Resolving` | selected resolution is being applied. |
+| `Resolved` | conflict closed and sync confirmed. |
+| `Ignored` | unsupported or intentionally ignored field. |
+| `Superseded` | newer sync state replaced this conflict. |
+
+## State transition invariants
+
+- `SignatureRejected` deliveries never become `Processing`.
+- `DeadLettered` deliveries require explicit replay or skip.
+- `PendingApproval` write intents never call provider before approval.
+- `Succeeded` write intents include provider native response or confirmation digest.
+- `Conflict` states must link to `ExternalSyncConflict`.
+- `Paused` provider/binding states block new backfills and writes but preserve webhook delivery records.
+
+## UI state mapping
+
+| State | UI tone | Action |
+| --- | --- | --- |
+| `Ready` | good | normal actions. |
+| `Degraded` | warning | show reason and retry/backfill actions. |
+| `RateLimited` | warning | show reset time. |
+| `Conflict` | danger/warning | link to conflict resolution. |
+| `Paused` | neutral | resume action. |
+| `Failed` | danger | show configuration fix. |
+| `DeadLettered` | danger | replay or skip action. |
+
+## Acceptance criteria
+
+- Every external backend resource has a stable phase and conditions.
+- Tests assert phase transitions, not only final data shape.
+- UI uses consistent status language across providers.
+- Audit events include phase transitions for deliveries, writes, and conflicts.