@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/external/external-backend-crds.md

@@ -0,0 +1,234 @@
+# External backend CRDs
+
+## Purpose
+
+This document defines the resource contracts for external backend providers, bindings, sync state, write intents, conflicts, and webhook deliveries.
+
+## Config resources
+
+### `ExternalBackendProvider`
+
+```yaml
+apiVersion: krate.a5c.ai/v1alpha1
+kind: ExternalBackendProvider
+metadata:
+  name: github-a5c
+  namespace: krate-org-a5c
+spec:
+  organizationRef: a5c
+  providerType: github
+  displayName: GitHub a5c-ai
+  baseUrl: https://github.com
+  apiBaseUrl: https://api.github.com
+  authRef:
+    secretRef:
+      name: github-app-a5c
+  capabilities:
+    issueTracking: true
+    cicd: true
+    gitForge: true
+status:
+  phase: Ready
+  conditions: []
+```
+
+### `ExternalBackendBinding`
+
+```yaml
+kind: ExternalBackendBinding
+spec:
+  organizationRef: a5c
+  providerRef: github-a5c
+  targetRef:
+    kind: Repository
+    name: krate
+  externalRef:
+    owner: a5c-ai
+    repository: krate
+    installationId: 123456
+  interfaces:
+    issueTracking:
+      enabled: true
+      mode: bidirectional
+    cicd:
+      enabled: true
+      mode: external-owned
+    gitForge:
+      enabled: true
+      mode: bidirectional
+```
+
+### `ExternalBackendSyncPolicy`
+
+```yaml
+kind: ExternalBackendSyncPolicy
+spec:
+  organizationRef: a5c
+  providerRef: github-a5c
+  webhookFirst: true
+  backfill:
+    interval: 15m
+    fullResyncInterval: 24h
+  writePolicy:
+    defaultMode: reviewed-write
+    agentWriteRequiresApproval: true
+  conflictPolicy:
+    defaultResolution: manual
+```
+
+## Aggregated resources
+
+| Kind | Purpose |
+| --- | --- |
+| `ExternalWebhookDelivery` | provider webhook delivery record and processing state. |
+| `ExternalSyncEvent` | normalized provider event. |
+| `ExternalSyncState` | cursor/high-watermark per provider/interface/resource scope. |
+| `ExternalWriteIntent` | Krate-originated write to provider. |
+| `ExternalSyncConflict` | field/resource conflict requiring resolution. |
+| `ExternalObjectLink` | external native ID/link attached to a Krate resource. |
+
+## Required labels
+
+- `krate.a5c.ai/org`;
+- `krate.a5c.ai/provider`;
+- `krate.a5c.ai/interface`;
+- `krate.a5c.ai/repository` when repository-scoped;
+- `krate.a5c.ai/external-owner` when provider owner/org is known.
+
+## Status conditions
+
+Providers and bindings should use:
+
+- `AuthReady`;
+- `InstallationReady`;
+- `WebhookReady`;
+- `IssueTrackingReady`;
+- `CicdReady`;
+- `GitForgeReady`;
+- `RateLimited`;
+- `BackfillHealthy`;
+- `ConflictsPresent`;
+- `Ready`.
+
+## Storage class
+
+- provider/binding/sync policy: CRD/etcd;
+- deliveries/events/state/write intents/conflicts/object links: aggregated API/Postgres;
+- large payloads/logs/artifacts: object storage by digest;
+- provider credentials: Kubernetes Secret in org namespace.
+
+## Detailed resource schemas
+
+### `ExternalWebhookDelivery.spec`
+
+```yaml
+organizationRef: a5c
+providerRef: github-a5c
+bindingRef: github-krate
+interfaceHints: [gitForge, issueTracking]
+deliveryId: "github-delivery-guid"
+eventType: pull_request
+action: opened
+receivedAt: 2026-05-11T12:00:00Z
+signature:
+  algorithm: sha256
+  verified: true
+source:
+  owner: a5c-ai
+  repository: krate
+payloadRef:
+  storage: object
+  digest: sha256:payload
+processing:
+  phase: Queued
+  attempts: 0
+```
+
+### `ExternalSyncEvent.spec`
+
+```yaml
+organizationRef: a5c
+providerRef: github-a5c
+bindingRef: github-krate
+sourceDelivery: github-delivery-guid
+interface: gitForge
+resourceKind: PullRequest
+nativeId: "42"
+nodeId: PR_kwDO...
+action: opened
+eventTime: 2026-05-11T12:00:00Z
+normalized:
+  repository: krate
+  pullRequest: 42
+  headSha: abcdef1234
+```
+
+### `ExternalWriteIntent.spec`
+
+```yaml
+organizationRef: a5c
+providerRef: github-a5c
+bindingRef: github-krate
+interface: issueTracking
+operation: createComment
+source:
+  kind: UserAction
+  actor: user:alice
+target:
+  kind: Issue
+  name: issue-42
+nativeTarget:
+  owner: a5c-ai
+  repository: krate
+  issueNumber: 42
+requestDigest: sha256:request
+approvalPolicy:
+  required: false
+idempotencyKey: a5c:issue-42:create-comment:01hx
+```
+
+### `ExternalObjectLink.spec`
+
+```yaml
+organizationRef: a5c
+providerRef: github-a5c
+bindingRef: github-krate
+localRef:
+  apiVersion: krate.a5c.ai/v1alpha1
+  kind: PullRequest
+  name: pr-42
+external:
+  interface: gitForge
+  nativeId: "42"
+  nativeNumber: 42
+  nodeId: PR_kwDO...
+  url: https://github.com/a5c-ai/krate/pull/42
+  apiUrl: https://api.github.com/repos/a5c-ai/krate/pulls/42
+  etag: W/"..."
+```
+
+## Provider type registry
+
+Provider types should be registered in a data-driven registry:
+
+```yaml
+providerType: github
+interfaces: [issueTracking, cicd, gitForge]
+hosting: [saas, ghe]
+authModes: [github-app, oauth-user]
+webhookSignature: hmac-sha256
+supportsGraphql: true
+supportsRest: true
+```
+
+Custom providers can be loaded later through plugin registration, but CRDs should not need a schema change for every provider.
+
+## Validation rules
+
+- `providerType` must exist in registry or use `custom` with explicit adapter ref.
+- enabled interface must be supported by provider descriptor.
+- binding target must be in the same org.
+- auth Secret must be in the org namespace.
+- write mode must be compatible with provider operations.
+- webhook endpoint must have a verification secret unless provider has a signed alternative.
+- `ExternalWriteIntent` cannot reference raw Secret values.

package/docs/external/external-backend-ui-spec.md

@@ -0,0 +1,151 @@
+# External backend UI specification
+
+## Purpose
+
+This document defines the full UI for external backend integrations: provider setup, bindings, sync health, conflicts, write intents, webhooks, and per-resource provider status.
+
+## Navigation
+
+Add org-scoped routes:
+
+| Route | Purpose |
+| --- | --- |
+| `/orgs/[org]/settings/external-backends` | provider list, add provider, health summary. |
+| `/orgs/[org]/settings/external-backends/[provider]` | provider detail, auth, capabilities, rate limits. |
+| `/orgs/[org]/settings/external-backends/[provider]/bindings` | repository/project bindings and interface modes. |
+| `/orgs/[org]/settings/external-backends/[provider]/webhooks` | webhook delivery log, replay, redelivery, failures. |
+| `/orgs/[org]/settings/external-backends/[provider]/sync` | sync state, backfill, cursors, queues. |
+| `/orgs/[org]/settings/external-backends/[provider]/conflicts` | conflicts and resolution. |
+| `/orgs/[org]/settings/external-backends/[provider]/writes` | write intents, approvals, retries. |
+
+Repository pages show external backend panels under Settings, Issues, Pull Requests, Runs, Hooks, and Code where relevant.
+
+## Provider list page
+
+Cards show:
+
+- provider name/type;
+- enabled interfaces;
+- auth health;
+- webhook health;
+- rate-limit/degraded state;
+- last backfill;
+- conflicts count;
+- write intents needing attention;
+- repositories bound.
+
+Primary actions:
+
+- add provider;
+- resync all;
+- pause/resume provider;
+- open YAML.
+
+## Add provider wizard
+
+Steps:
+
+1. Select provider type: GitHub, GitLab, Bitbucket, Azure DevOps, Jira, Linear, Buildkite, CircleCI, Jenkins, Gitea, Custom.
+2. Select hosting: SaaS or self-managed and base URLs.
+3. Select interfaces to enable.
+4. Configure auth and Secret refs.
+5. Validate credentials and capabilities.
+6. Select org/repository/project bindings.
+7. Choose sync ownership modes.
+8. Configure webhook endpoint and secret.
+9. Review generated YAML.
+10. Apply and start initial backfill.
+
+## Binding UI
+
+Binding rows show:
+
+- Krate target resource;
+- external owner/project/repo key;
+- enabled interfaces;
+- mode per interface;
+- last sync state;
+- native provider URL;
+- conflict count;
+- actions: sync now, edit modes, disconnect, view YAML.
+
+## Resource badges
+
+Synced resources display:
+
+- provider icon/name;
+- native URL;
+- sync phase: current, stale, paused, conflict, degraded, write pending;
+- ownership: mirrored, external-owned, Krate-owned, bidirectional;
+- last synced time;
+- pending write/conflict indicator.
+
+## Conflict resolution UI
+
+Conflict detail shows:
+
+- resource and native URL;
+- field conflicts;
+- local value;
+- external value;
+- last local generation;
+- provider version/etag;
+- policy recommendation;
+- actions: keep external, apply Krate, manual edit, ignore unsupported, retry sync.
+
+## Write intent UI
+
+Write intent detail shows:
+
+- actor and source action;
+- target provider/interface;
+- native operation;
+- request preview with secrets redacted;
+- approval state;
+- retry count;
+- provider response summary;
+- linked audit events;
+- actions: approve, reject, retry, cancel, open native object.
+
+## Webhook and sync UI
+
+Webhook page shows:
+
+- delivery ID;
+- event/action;
+- repository/project;
+- received time;
+- signature status;
+- processing phase;
+- response code;
+- normalized event ID;
+- replay action.
+
+Sync page shows:
+
+- high-watermarks/cursors by interface/resource kind;
+- current queue depth;
+- rate-limit budget;
+- backfill schedule;
+- last full resync;
+- paused/degraded reasons.
+
+## Repository settings integration
+
+`/orgs/[org]/repositories/[repo]/settings` gains an External Backends section:
+
+- current provider binding;
+- interface modes;
+- sync health;
+- branch protection ownership;
+- issue/PR/CI ownership;
+- webhook delivery status;
+- quick link to provider settings.
+
+## Acceptance criteria
+
+- Users can configure a provider without writing YAML.
+- YAML remains visible for every provider resource.
+- UI never enables unsupported provider operations.
+- Conflicts and write intents are first-class and actionable.
+- Every synced resource shows provider ownership and native link.

package/docs/external/external-backend-ux-flows.md

@@ -0,0 +1,115 @@
+# External backend UX flows
+
+## Purpose
+
+This document turns the UI specification into user-facing flows that can become acceptance tests and implementation tickets.
+
+## Flow: connect GitHub provider
+
+1. Org admin opens `/orgs/a5c/settings/external-backends`.
+2. Clicks `Add provider`.
+3. Selects `GitHub`.
+4. Selects `GitHub App` auth.
+5. Enters or selects Kubernetes Secret refs for app ID, private key, and webhook secret.
+6. Enters installation ID or authorizes installation discovery.
+7. Selects interfaces: Issues, Actions/CI, Git forge.
+8. Runs capability check.
+9. Selects repositories to bind.
+10. Chooses sync modes per interface.
+11. Reviews YAML.
+12. Applies provider and binding.
+13. UI shows initial backfill progress and webhook status.
+
+Acceptance:
+
+- no token/private key value is shown after entry;
+- unsupported operations are explained;
+- provider and binding resources are created with org labels;
+- initial backfill status appears.
+
+## Flow: connect Jira for issues only
+
+1. Admin selects `Jira` provider.
+2. UI shows only Issue Tracking interface.
+3. Admin configures base URL, auth Secret, and project keys.
+4. Chooses read-only or bidirectional issue sync.
+5. Applies binding to a Krate repository or org work board.
+6. Issue pages show Jira badge and native links.
+
+Acceptance:
+
+- CI/CD and git forge options are disabled;
+- PR and pipeline pages do not claim Jira ownership;
+- Jira rich text conversion warnings are visible when relevant.
+
+## Flow: combine GitHub forge with Buildkite CI
+
+1. Repository has GitHub binding for git forge and issue tracking.
+2. Admin adds Buildkite provider with CI/CD only.
+3. Admin binds Buildkite pipelines to the same Krate repository.
+4. Runs page shows GitHub PR context and Buildkite builds together.
+5. Agent trigger rules can match Buildkite failures and write PR comments through GitHub after approval.
+
+Acceptance:
+
+- separate provider badges are visible;
+- CI actions go to Buildkite, PR comments go to GitHub;
+- audit records show both providers when a flow crosses interfaces.
+
+## Flow: resolve sync conflict
+
+1. User opens Inbox or provider Conflicts page.
+2. Selects conflict for issue labels.
+3. UI shows local and external values and sync history.
+4. User chooses `Keep external`.
+5. Conflict controller updates Krate projection and closes conflict.
+6. Audit records decision.
+
+Acceptance:
+
+- no hidden overwrite occurs;
+- user can inspect native provider link;
+- resolved state is visible in resource detail.
+
+## Flow: reviewed external write from agent
+
+1. Agent proposes GitHub PR comment or label update.
+2. Krate creates `ExternalWriteIntent` with request digest.
+3. UI shows approval in Inbox and run detail.
+4. Reviewer approves.
+5. Write controller posts to GitHub.
+6. Webhook or read-back confirms write.
+7. Run detail and PR page show result.
+
+Acceptance:
+
+- agent cannot write directly without Krate approval policy;
+- request preview is redacted;
+- native URL and provider response summary are visible.
+
+## Flow: webhook recovery
+
+1. Webhook delivery fails processing and becomes `DeadLettered`.
+2. Provider page shows failed delivery.
+3. Operator opens delivery detail and sees normalized error.
+4. Operator chooses replay.
+5. Delivery re-enters queue and succeeds or remains dead-lettered with updated attempts.
+
+Acceptance:
+
+- duplicate replay is idempotent;
+- raw payload access is permission-gated;
+- sync state updates after replay.
+
+## Flow: provider rate limit
+
+1. Provider reaches low rate-limit threshold.
+2. Provider status becomes `Degraded` or `RateLimited`.
+3. Backfill pauses; webhook ingest continues.
+4. UI shows reset time and impacted interfaces.
+5. Sync resumes after reset.
+
+Acceptance:
+
+- user actions that require provider writes are disabled or queued by policy;
+- status clearly separates webhook ingestion from API backfill.

package/docs/external/external-object-mapping.md

@@ -0,0 +1,125 @@
+# External object mapping spec
+
+## Purpose
+
+This document defines canonical object mappings between provider-native objects and Krate resources. The goal is loss-aware sync: Krate should preserve provider identity and important provider-specific fields even when not all fields fit a first-class Krate resource.
+
+## Mapping principles
+
+- Preserve native ID, URL, node/global ID, and provider version fields.
+- Normalize common fields into Krate resources.
+- Store unsupported provider-specific fields in an extension map with schema version.
+- Avoid lossy writes unless the user explicitly accepts field loss.
+- Keep provider-specific rich text formats as source plus rendered Markdown/HTML where safe.
+
+## Common external envelope
+
+```yaml
+external:
+  providerRef: github-a5c
+  bindingRef: github-krate
+  interface: gitForge
+  nativeKind: pull_request
+  nativeId: "123456"
+  nativeNumber: 42
+  nodeId: PR_kwDO...
+  url: https://github.com/a5c-ai/krate/pull/42
+  apiUrl: https://api.github.com/repos/a5c-ai/krate/pulls/42
+  version:
+    etag: W/"..."
+    updatedAt: 2026-05-11T12:00:00Z
+    sha: abcdef1234
+  extensions:
+    providerType: github
+    schemaVersion: github-rest-2022-11-28
+    fields: {}
+```
+
+## Issue mapping
+
+| Provider field | Krate field |
+| --- | --- |
+| title | `Issue.spec.title` |
+| body/description | `Issue.spec.body` plus `external.extensions.bodyFormat` |
+| state/status | `Issue.status.phase` and `Issue.spec.state` |
+| labels | `Issue.metadata.labels` and issue label projection |
+| assignees | `Issue.spec.assignees` via identity mapping |
+| milestone/sprint/cycle | `Issue.spec.milestone` or extension |
+| comments | issue activity/comment projection |
+| timestamps | `status.createdAt`, `status.updatedAt`, `status.closedAt` |
+
+Provider notes:
+
+- Jira status transitions need a transition operation, not a simple `state` patch.
+- Linear workflow states map to issue phase plus provider extension.
+- GitHub PR-backed issues link to `PullRequest`.
+
+## Pipeline mapping
+
+| Provider field | Krate field |
+| --- | --- |
+| workflow/pipeline name | `Pipeline.spec.workflow` |
+| run/build ID | `Pipeline.external.nativeId` |
+| branch/ref | `Pipeline.spec.ref` |
+| sha | `Pipeline.spec.sha` |
+| status/conclusion | `Pipeline.status.phase` and `status.conclusion` |
+| jobs | `Job` projections |
+| logs | lazy `Artifact`/log ref |
+| artifacts | `AgentArtifact`/`Artifact` projection by digest or native URL |
+| rerun/cancel | `ExternalWriteIntent` operation |
+
+## Pull request mapping
+
+| Provider field | Krate field |
+| --- | --- |
+| title/body | `PullRequest.spec.title/body` |
+| number/IID | `external.nativeNumber` |
+| source branch | `PullRequest.spec.head` |
+| target branch | `PullRequest.spec.base` |
+| head SHA | `PullRequest.status.headSha` |
+| merge state | `PullRequest.status.mergeState` |
+| reviewers/reviews | `Review` projections |
+| checks | linked `Pipeline`/`Job`/check projections |
+| labels/assignees | shared issue-like fields where provider supports them |
+
+## Repository mapping
+
+| Provider field | Krate field |
+| --- | --- |
+| owner/name/path | `Repository.metadata.name`, `spec.external.owner/path` |
+| visibility | `Repository.spec.visibility` |
+| default branch | `Repository.spec.defaultBranch` |
+| clone URLs | `Repository.status.cloneUrls` |
+| archived/disabled | `Repository.status.phase` and extension |
+| permissions/collaborators | `RepositoryPermission` projections |
+| deploy keys | `SSHKey`/deploy-key projections |
+| branch protection | `BranchProtection`/`RefPolicy` projections |
+
+## Rich text conversion
+
+Providers may use different body formats:
+
+- Markdown: GitHub, GitLab, many Git forges;
+- Atlassian Document Format: Jira Cloud;
+- provider-specific markdown extensions: Linear/GitLab;
+- HTML fragments: some legacy systems.
+
+Krate stores:
+
+```yaml
+body:
+  markdown: safe normalized markdown
+  sourceFormat: atlassian-document-format
+  sourceDigest: sha256:...
+  renderWarnings: []
+```
+
+Writes should preserve source format when possible or mark conversion loss.
+
+## Acceptance criteria
+
+- Every synced object has an external envelope.
+- Unsupported provider fields are retained in extensions.
+- Writes do not silently drop unsupported fields.
+- Rich text conversion is explicit and testable.
+- Mapping docs are used by provider contract tests.

package/docs/external/git-forge-interface.md

@@ -0,0 +1,68 @@
+# Git forge interface
+
+## Purpose
+
+The git forge interface syncs repository, pull request, ref, commit, key, collaborator, and repository policy state. It is the broadest external backend interface and is supported by GitHub, GitLab, Bitbucket, Gitea, and similar systems.
+
+## Provider contract
+
+```ts
+interface GitForgeProvider {
+  listRepositories(cursor): Page<ExternalRepository>;
+  getRepository(ref): ExternalRepository;
+  createRepository(input): ExternalRepository;
+  updateRepository(ref, patch): ExternalRepository;
+  listPullRequests(repoRef, cursor): Page<ExternalPullRequest>;
+  getPullRequest(ref): ExternalPullRequest;
+  createPullRequest(input): ExternalPullRequest;
+  updatePullRequest(ref, patch): ExternalPullRequest;
+  mergePullRequest(ref, options): ExternalPullRequest;
+  listRefs(repoRef, cursor): Page<ExternalRef>;
+  getCommit(repoRef, sha): ExternalCommit;
+  listDeployKeys(repoRef, cursor): Page<ExternalDeployKey>;
+  syncDeployKeys(repoRef, desired): SyncResult;
+  listCollaborators(repoRef, cursor): Page<ExternalCollaborator>;
+  syncBranchProtection(repoRef, desired): SyncResult;
+}
+```
+
+## Resource mapping
+
+| External concept | Krate resource/projection |
+| --- | --- |
+| repository | `Repository` |
+| pull request / merge request | `PullRequest` |
+| review | `Review` |
+| PR comment/review thread | `ReviewComment` projection or activity stream |
+| branch/tag/ref | `GitRef` projection or repository status |
+| commit | `Commit` projection or lazy detail |
+| deploy key/SSH key | `SSHKey` / `RepositoryPermission` / deploy-key projection |
+| collaborator/team permission | `RepositoryPermission` |
+| branch protection | `BranchProtection` / `RefPolicy` |
+| repository webhook | `WebhookSubscription` |
+
+## GitHub mapping
+
+GitHub repositories map to Krate `Repository`; GitHub pull requests map to `PullRequest`; PR reviews/comments map to `Review` and activity projections; deploy keys map to SSH key/deploy-key projections; branch protection maps to `BranchProtection` and `RefPolicy` where fields overlap.
+
+## Sync rules
+
+- Webhooks handle `repository`, `pull_request`, `pull_request_review`, `pull_request_review_comment`, `push`, `create`, `delete`, `branch_protection_rule`, `deploy_key`, and membership/collaborator-related events where available.
+- Backfill lists repositories, PRs, refs, branch protection, keys, and collaborators.
+- PR sync must coordinate with issue sync because provider issue numbers and PR numbers may share namespace.
+- Git operations can use provider clone URLs and provider credentials; Krate should not require PATs.
+- Branch protection writes require explicit ownership mode and permission review.
+
+## User-facing changes
+
+- Repository settings show whether GitHub or Krate owns each setting.
+- PR pages show native provider link, sync state, and conflict status.
+- SSH/deploy key panels show mirrored vs Krate-managed keys.
+- Branch protection editor can operate read-only, write-through, or reviewed-write depending on sync policy.
+
+## Acceptance criteria
+
+- A git-forge-only provider can sync repos/PRs/refs without issue or CI support.
+- PR state converges from webhooks and periodic backfill.
+- Branch protection/key writes are explicit and audited.
+- GitHub issue/PR shared numbering does not create duplicate records.