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

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:
+
+- Kradle 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, Kradle-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 Kradle, 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 Kradle 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 Kradle 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 Kradle 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. Kradle 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 Kradle 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 Kradle resources. The goal is loss-aware sync: Kradle should preserve provider identity and important provider-specific fields even when not all fields fit a first-class Kradle resource.
+
+## Mapping principles
+
+- Preserve native ID, URL, node/global ID, and provider version fields.
+- Normalize common fields into Kradle 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-kradle
+  interface: gitForge
+  nativeKind: pull_request
+  nativeId: "123456"
+  nativeNumber: 42
+  nodeId: PR_kwDO...
+  url: https://github.com/a5c-ai/kradle/pull/42
+  apiUrl: https://api.github.com/repos/a5c-ai/kradle/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 | Kradle 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 | Kradle 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 | Kradle 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 | Kradle 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.
+
+Kradle 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 | Kradle 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 Kradle `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; Kradle should not require PATs.
+- Branch protection writes require explicit ownership mode and permission review.
+
+## User-facing changes
+
+- Repository settings show whether GitHub or Kradle owns each setting.
+- PR pages show native provider link, sync state, and conflict status.
+- SSH/deploy key panels show mirrored vs Kradle-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.

package/docs/external/github-integration-design.md

@@ -0,0 +1,151 @@
+# GitHub integration design
+
+## Purpose
+
+GitHub is the first full external backend provider for Kradle. It can support all three unified interfaces: issue tracking, CI/CD, and git forge. Kradle should integrate through a GitHub App by default, with optional user-attributed actions when a user token is available and admitted.
+
+## Authentication model
+
+Preferred auth:
+
+```yaml
+kind: ExternalBackendProvider
+spec:
+  providerType: github
+  auth:
+    mode: github-app
+    appIdSecretRef:
+      name: github-app-a5c
+      key: app-id
+    privateKeySecretRef:
+      name: github-app-a5c
+      key: private-key.pem
+    webhookSecretRef:
+      name: github-app-a5c
+      key: webhook-secret
+```
+
+Flow:
+
+1. Kradle signs a GitHub App JWT.
+2. Kradle exchanges it for installation access tokens per org/repository installation.
+3. Tokens are cached only until expiry and never stored in status.
+4. User-attributed actions use GitHub App user access tokens when available and required.
+5. All actions still pass Kradle org/RBAC/admission checks.
+
+## GitHub provider capabilities
+
+```yaml
+capabilities:
+  issueTracking:
+    issues: true
+    comments: true
+    labels: true
+    milestones: true
+    projects: optional
+  cicd:
+    actionsWorkflowRuns: true
+    workflowJobs: true
+    checks: true
+    statuses: true
+    selfHostedRunners: optional
+  gitForge:
+    repositories: true
+    pullRequests: true
+    reviews: true
+    refs: true
+    commits: true
+    deployKeys: true
+    branchProtection: true
+    collaborators: true
+```
+
+## Installation binding
+
+```yaml
+kind: ExternalBackendBinding
+spec:
+  organizationRef: a5c
+  providerRef: github-a5c
+  externalRef:
+    owner: a5c-ai
+    repository: kradle
+    installationId: 123456
+  interfaces:
+    issueTracking:
+      enabled: true
+      mode: bidirectional
+    cicd:
+      enabled: true
+      mode: external-owned
+    gitForge:
+      enabled: true
+      mode: bidirectional
+```
+
+## Webhook events
+
+Recommended GitHub events:
+
+| Interface | Events |
+| --- | --- |
+| Issue tracking | `issues`, `issue_comment`, `label`, `milestone`, `projects_v2_item` where available. |
+| CI/CD | `workflow_run`, `workflow_job`, `check_run`, `check_suite`, `status`, `push`. |
+| Git forge | `repository`, `pull_request`, `pull_request_review`, `pull_request_review_comment`, `push`, `create`, `delete`, `branch_protection_rule`, `deploy_key`. |
+| Provider lifecycle | `installation`, `installation_repositories`, `meta`. |
+
+Webhook delivery handling:
+
+- validate signature before parsing;
+- record delivery ID and event type;
+- respond quickly with 2XX after enqueue;
+- process asynchronously through Kradle queue/controller;
+- dedupe by provider, delivery ID, event, and installation;
+- support redelivery and replay.
+
+## Backfill and repair
+
+Backfill should run when:
+
+- provider binding is created;
+- webhook delivery is missed or failed;
+- rate limit window recovers;
+- manual `resync` is requested;
+- native object has stale `lastSyncedAt`;
+- provider installation changes repository access.
+
+GitHub backfill strategy:
+
+- GraphQL for list hydration where it reduces calls and provides cursors;
+- REST for endpoints with first-class Actions, checks, deploy keys, webhooks, branch protection, and logs;
+- conditional requests with ETags where useful;
+- rate-limit aware scheduling by installation and org.
+
+## Write paths
+
+| Action | Default mode |
+| --- | --- |
+| create/update issue | write-through or reviewed-write by policy. |
+| comment on issue/PR | write-through for humans, reviewed-write for agents. |
+| update labels | bidirectional with conflict detection. |
+| rerun/cancel workflow | write-through after permission review. |
+| create/update PR | reviewed-write for agents; write-through for authorized humans. |
+| merge PR | external-owned or reviewed-write; require branch protection status. |
+| deploy key update | Kradle-owned or reviewed-write. |
+| branch protection update | reviewed-write unless org policy says Kradle-owned. |
+
+## GitHub-specific conflicts
+
+- Issue and PR share number namespace; PR-backed issue projections must link to PR.
+- Labels can be edited externally while Kradle has pending desired changes.
+- Branch protection fields may not map 1:1 to Kradle `RefPolicy`.
+- Workflow runs may be rerun externally while Kradle still shows an old attempt.
+- Force-push updates PR head SHA and invalidates cached diff/check context.
+
+## UI requirements
+
+- Provider setup wizard for GitHub App app ID, private key, webhook secret, installation ID, owner, repository selection, and selected interfaces.
+- Repository settings page shows GitHub binding and per-interface mode.
+- Issue/PR/run pages show native GitHub link, sync status, and conflict banner.
+- Actions/runs page can filter external GitHub Actions vs Kradle-native pipelines.
+- Webhook page shows delivery IDs, replay, redelivery, and backfill status.

package/docs/external/issue-tracking-interface.md

@@ -0,0 +1,66 @@
+# Issue tracking interface
+
+## Purpose
+
+The issue tracking interface syncs externally managed work items into Kradle and optionally writes changes back. It covers issues, comments, labels, milestones, assignees, projects, saved views, reactions, and issue events.
+
+## Provider contract
+
+A provider implementing this interface should support some or all of:
+
+```ts
+interface IssueTrackingProvider {
+  listIssues(cursor): Page<ExternalIssue>;
+  getIssue(ref): ExternalIssue;
+  createIssue(input): ExternalIssue;
+  updateIssue(ref, patch): ExternalIssue;
+  closeIssue(ref, reason): ExternalIssue;
+  listComments(issueRef, cursor): Page<ExternalComment>;
+  createComment(issueRef, input): ExternalComment;
+  updateComment(commentRef, patch): ExternalComment;
+  listLabels(cursor): Page<ExternalLabel>;
+  syncLabels(desired): SyncResult;
+  listEvents(issueRef, cursor): Page<ExternalIssueEvent>;
+}
+```
+
+Capabilities are negotiated; read-only providers can omit mutating operations.
+
+## Resource mapping
+
+| External concept | Kradle resource/projection |
+| --- | --- |
+| issue/work item | `Issue` |
+| issue comment | `IssueComment` aggregated projection or `Issue.status.comments` summary |
+| label | `IssueLabel` config/projection or labels on `Issue` |
+| milestone | `Milestone` projection or metadata field |
+| assignee | `User`/`Team` references plus external identity mapping |
+| project field | `View`, `Selector`, or provider-specific field projection |
+| linked PR | `PullRequest` edge |
+| issue event | `ExternalSyncEvent` or issue activity stream |
+
+## GitHub mapping
+
+GitHub Issues map naturally to Kradle `Issue`. GitHub pull requests also have issue numbers and issue-like comments/labels, so the GitHub issue provider must avoid duplicating PR-backed issues. A GitHub issue with `pull_request` metadata should link to the `PullRequest` projection rather than become an independent work item unless the UI explicitly needs a combined activity view.
+
+## Sync rules
+
+- Webhooks handle `issues`, `issue_comment`, `label`, `milestone`, and assignment events.
+- Backfill/poll handles missed events and periodic consistency checks.
+- Cursor sync stores provider cursor or `updated_at` high-water mark.
+- Writes include idempotency keys where provider supports them; otherwise Kradle stores write intent and native result.
+- Conflicts create `ExternalSyncConflict` when local desired state and external state both changed since last sync.
+
+## User-facing changes
+
+- Issue pages show external provider badges, native URLs, sync status, and conflict state.
+- Editing an externally owned issue shows whether the change writes through, opens a reviewed change, or is disabled.
+- Comments show source: Kradle, GitHub, imported, or agent.
+- Label management shows external ownership and drift.
+
+## Acceptance criteria
+
+- A read-only issue provider can mirror issues and comments without write permissions.
+- A bidirectional provider can update title/body/state/labels/comments and detect conflicts.
+- GitHub PR-backed issues link to PRs instead of duplicating work items.
+- Webhook replay and cursor backfill converge to the same state.