Skip to content

ROADMAP.md

Latest commit

 

History

History
1031 lines (770 loc) · 59.7 KB

ROADMAP.md

File metadata and controls

1031 lines (770 loc) · 59.7 KB
Raw

ROADMAP.md – PatchPlane v2 Alpha Execution Plan

Date: June 25, 2026
Source of truth: SPEC.md
Architecture: Effect v4 / effect-smol core with plugin-based infrastructure boundaries
Status: Public OSS roadmap for the alpha trust-boundary loop

0. Purpose of this roadmap

This roadmap tracks the public execution path for PatchPlane's first alpha: one end-to-end, human-gated trust-boundary workflow for AI-generated code changes.

SPEC.md defines the product thesis, trust model, architecture boundaries, and alpha success criteria. This roadmap defines the implementation order, milestone status, and public acceptance criteria. docs/critical-path.md connects those milestones into the shortest product and release path from intake to a reproducible Patch Report.

This file is intentionally OSS-safe. It documents product and engineering direction only. It does not include pricing strategy, customer notes, sales pipeline, founder/company strategy, or private credentials.

1. Current objective

PatchPlane v2 has completed the authenticated foundation work and is now focused on one developer-first outcome: trusting or rejecting an AI-generated patch before merge.

The product primitive is the Patch Report: an evidence-backed report that tells a developer what changed, what ran, where it ran, what passed or failed, what evidence exists, and who approved or rejected it.

The first credible independent pre-merge trust-boundary demo is:

GitHub pull-request intake
→ authenticated or signed PatchPlane workflow
→ repository allowlist/access verification
→ exact base/head candidate freeze
→ trusted bounded verification plan
→ Daytona requirement execution
→ optional read-only Pi review
→ candidate-bound logs/tests/browser evidence
→ Patch Report
→ PatchPlane policy/review decision
→ human approve/reject
→ one canonical GitHub comment and exact-head check
→ persisted provenance timeline

The immediate slice remains closure of the smallest workflow that shows an exact incoming AI-generated PR candidate staying untrusted until candidate-bound sandbox execution, Patch Report evidence, read-only review, and explicit decision complete. The alpha verification envelope stays within Daytona: Linux is the implemented baseline, windows-small is the bounded Windows target, and browser/GUI verification uses Daytona Computer Use on supported Linux or Windows sandboxes only when explicitly required. macOS and production-credential-dependent checks remain blocked.

For alpha, these remain deferred:

  • complex provenance graph UI
  • multiple sandbox providers beyond Daytona
  • multiple Git forges beyond GitHub
  • weighted scoring and broad policy editor work
  • full enterprise RBAC beyond current organization-level auth
  • plugin marketplace work
  • billing or monetization work
  • ClickHouse/OpenTelemetry collector infrastructure
  • PostHog AI observability dashboards
  • Origin-style forge behavior

2. Public alpha architecture boundary

PatchPlane's alpha is built around public, replaceable service boundaries:

AuthService              -> WorkOS AuthKit
StorageService           -> Convex workflow state/read model
SourceControlService     -> GitHub App / Octokit
SandboxService           -> Daytona
RuntimeService           -> Pi coding-agent runtime (sandbox-backed for alpha)
ModelGatewayService      -> Cloudflare AI Gateway
ArtifactsService         -> Cloudflare R2
TelemetryService         -> Sentry + Effect logs/spans
AnalyticsService         -> PostHog product events
InfraProvisioning        -> Alchemy in apps/infra

Important boundaries:

  • packages/core must not import WorkOS, Convex, GitHub, Daytona, Pi, Cloudflare, Alchemy, Sentry, PostHog, or TanStack Start.
  • SDK-specific objects stay inside plugin packages or app composition code.
  • Convex stores workflow/provenance metadata and realtime read-model state.
  • Cloudflare R2 stores large raw evidence artifacts.
  • Sentry is for operational debugging, not product truth.
  • PostHog is for product analytics, not provenance truth.
  • ClickHouse is deferred until high-volume trace analytics are needed.
  • Alchemy provisions PatchPlane-owned infrastructure; it does not replace runtime product services.

3. Alpha data ownership model

PatchPlane-owned product truth should use PatchPlane-owned domain concepts:

WorkflowRun
ExternalWorkflowRef
RuntimeEvent
SandboxPolicy
CandidatePatchSet
PatchReport
ReviewFinding
PolicyDecision
HumanDecision
PublicationResult
ProvenanceTimeline
EvidenceArtifact
BrowserVerificationResult

Vendor-specific data must be normalized before crossing into core or UI-facing product state:

Pi events               -> RuntimeEvent
Daytona objects         -> Sandbox/session/provenance metadata
Octokit objects         -> SourceControlService results
WorkOS objects          -> Actor/Workspace/Membership/Permission
Convex documents        -> decoded domain values
Sentry traces           -> operational telemetry only
PostHog events          -> product analytics only
R2 objects              -> EvidenceArtifact references

4. Milestones

M0 — Repo alignment and dependency baseline

Status: Complete for the M0-M10 alpha architecture baseline

Public goals:

  • Keep /vendor sources as research-only references.
  • Use normal package dependencies in PatchPlane packages.
  • Pin Effect v4 / effect-smol consistently where used.
  • Use @daytona/sdk for Daytona integration.
  • Use Pi coding-agent behavior behind a runtime boundary. For alpha, Pi executes inside Daytona rather than being bundled into the web/control-plane Worker.
  • Use Octokit/GitHub App APIs behind a GitHub plugin boundary.
  • Keep apps/client as the TanStack Start composition root.
  • Keep Convex deployment functions under packages/backend/convex for now.
  • Target Node 22.19+ for server/plugin runtime work.

Acceptance criteria:

  • The repo structure supports packages/domain, packages/core, packages/plugins, apps/client, and packages/backend/convex.
  • packages/core imports only PatchPlane domain/core dependencies and Effect.
  • Vendor research does not leak into runtime imports.

M1 — Create v2 package skeleton

Status: Complete for foundation experiment

Target structure:

packages/domain
packages/core
packages/plugins
packages/backend/convex
packages/cli
apps/client

Tasks:

  • Create packages/domain.
  • Create packages/core.
  • Create packages/plugins.
  • Keep existing apps/client as the app composition root.
  • Add explicit package subpath exports.
  • Add package-level typecheck/test scripts.
  • Include new packages in root typecheck/lint scripts.

Acceptance criteria:

  • bun install succeeds.
  • bun run typecheck reaches the new packages.
  • packages/core does not import app/plugin/vendor SDKs.

M2 — Domain schemas and typed errors

Status: Foundation slice working

Tasks:

  • Implement branded/domain IDs for foundation entities.
  • Implement Actor, Workspace, Membership, and Permission schemas.
  • Implement PromptRequest and WorkflowRun schemas.
  • Implement typed errors for auth, storage, source control, GitHub, workflow state, and validation failures.
  • Add traceId to foundation request/run schemas.
  • Add generic ExternalWorkflowRef and WorkflowIntake schemas.

Acceptance criteria:

  • Domain schemas decode unknown input.
  • External/plugin data entering core has a decode path.
  • Typed errors are PatchPlane-owned and do not expose raw SDK error types.

M3 — Core service contracts

Status: Complete for alpha core service contracts

Tasks:

  • Define AuthService.
  • Define experimental StorageService with prompt and external-intake creation paths.
  • Define generic SourceControlService.
  • Define GitHub-specific GitHubWebhookService.
  • Define minimal TelemetryService interface.
  • Define ArtifactsService interface for evidence storage.
  • Define ModelGatewayService interface for agent model access configuration.
  • Implement StartWorkflowFromPrompt.
  • Implement StartWorkflowFromIntake with repository verification before persistence.
  • Add structured context fields with traceId.

Acceptance criteria:

  • Core workflows depend only on services, not SDKs.
  • Storage/auth/source-control failures map to typed PatchPlane errors.
  • Full workflow timeline/event history remains deferred until RuntimeEvent, ReviewRun, and decision schemas exist.

M4 — Convex realtime orchestration/read-model boundary

Status: Authenticated foundation slice working

Tasks:

  • Keep Convex deployment functions in packages/backend/convex.
  • Add minimal Convex mutations/queries needed by the foundation storage path.
  • Keep workflow-start creation transactional.
  • Store traceId on foundation records.
  • Gate public workflow-start writes with WorkOS JWT validation and mirrored membership authorization.
  • Gate reads with WorkOS identity and mirrored active membership checks.
  • Add externalWorkflowRefs for signed/external provider events.

Acceptance criteria:

  • Convex backend code remains isolated under packages/backend/convex.
  • Convex generated API exposes public reads and the signed external-ingestion mutation.
  • Convex remains the alpha realtime read-model/orchestration implementation, not a product-truth shortcut.

M5 — Convex Storage Plugin

Status: Authenticated/trusted foundation slice working

Tasks:

  • Define initial Convex schema for foundation entities.
  • Add ConvexConfig through Effect Config.
  • Implement domain ↔ Convex document mapping.
  • Implement authenticated workflow creation through Convex mutation with WorkOS JWT.
  • Implement signed external-intake workflow creation.
  • Decode Convex documents back through domain schemas.

Acceptance criteria:

  • Foundation and external-intake records persist through StorageService.
  • Core does not import Convex APIs.
  • Convex access stays inside plugin/backend boundaries.

M6 — App composition root and first vertical action

Status: Runtime, AuthKit composition, authenticated workflow path, and CLI onboarding foundation working

Tasks:

  • Compose WorkOS and Convex plugin layers in the app root.
  • Create a managed Effect runtime for app/server actions.
  • Wire WorkOS AuthKit and Convex AuthKit providers.
  • Productize the visible prompt/workflow UI for the current alpha shell.
  • Add initial Effect logs and local JSONL logs.
  • Add packages/cli as an Effect CLI onboarding surface.

Acceptance criteria:

  • Authenticated WorkOS users can create PromptRequest and WorkflowRun records through the core workflow.
  • App routes/server functions talk to core through the managed runtime.
  • CLI commands run through PatchPlane-owned service layers.

5. Current verified experiment

The current foundation verifies these paths:

TanStack Start server function
→ WorkOS session extraction
→ AuthRequestContext
→ WorkOSAuthPlugin.requirePermission("prompt:create")
→ StorageService
→ ConvexStoragePlugin
→ Convex authenticated mutation
→ promptRequests + workflowRuns

/api/github/webhook
→ raw GitHub payload + signature headers
→ GitHubWebhookService.verifyWebhook
→ GitHub-specific normalization
→ WorkflowIntake + ExternalWorkflowRef
→ repository allowlist/access verification
→ StorageService.createWorkflowFromIntake
→ Convex signed external-ingestion mutation

Automated checks currently cover the foundation, backend Convex behavior, CLI integration, domain/core/plugin tests, typechecking, linting, and app build.

Remaining manual smoke before external alpha:

  • Hosted WorkOS AuthKit sign-in and callback with real credentials.
  • Convex WorkOS webhook delivery for users and organization memberships.
  • Browser workflow start from /app with a real organization membership.
  • Real GitHub App webhook delivery to /api/github/webhook with required alpha configuration.

6. End-to-end alpha backlog

M1–M6 are the authenticated foundation. Continue with the trust loop: WorkOS hardening → GitHub completion → Daytona → Cloudflare infra → Pi → evidence capture → review/decision/publication.

M6.5 — WorkOS / Convex auth hardening

Status: In progress / mostly complete

Tasks:

  • Add WorkOS plugin configuration with Effect Config.
  • Implement WorkOS User, Organization, and OrganizationMembership mappings.
  • Implement WorkOS role(s) → PatchPlane permission mapping.
  • Wire WorkOS AuthKit to real session data.
  • Forward AuthKit access tokens through authenticated workflow paths.
  • Add Convex-side mirrored users and memberships.
  • Add mirrored membership checks in Convex reads/writes.
  • Add documented backfill/update strategy for dynamic role/permission changes.
  • Add resource-level WorkOS Authorization API checks when repository/project-scoped permissions are introduced.

Acceptance criteria:

  • User-facing workflow starts are authorized by WorkOS/Convex identity and mirrored permissions.
  • WorkOS SDK objects do not cross into core.

M7 — GitHub Provider Plugin

Status: Complete for alpha intake plus issue-comment/check-run foundations; exact incoming-candidate publication remains in M10 follow-up scope

Tasks:

  • Add GitHubConfig.
  • Implement installation-token broker with Octokit GitHub App APIs.
  • Implement repository access verification.
  • Implement issue-comment publication.
  • Verify signed webhooks before normalization or persistence.
  • Normalize initial GitHub events into generic workflow intake values.
  • Persist external event references for idempotency.
  • Require an alpha repository allowlist for webhook-to-workspace routing.
  • Implement check-run publication.
  • Publish only one canonical report and check against the exact incoming candidate head; draft PR creation is not part of the alpha verifier.
  • Add user-visible GitHub comment and check-run publication paths for the alpha demo.

Acceptance criteria:

  • GitHub App installation-token flow is isolated inside packages/plugins.
  • Verified GitHub events become generic WorkflowIntake values.
  • PatchPlane can publish an alpha result back to GitHub without leaking Octokit objects into core.

M7.5 — Minimal TelemetryService and operational visibility

Status: In progress — foundational Sentry capture is complete; critical-path coverage and sensitive-data hardening are open

Scope:

  • Keep a minimal, provider-neutral TelemetryService interface.
  • Keep Effect structured logs and span-like context.
  • Use Sentry for operational errors, bounded critical-path breadcrumbs, and debugging.
  • Treat observability input as a data-egress boundary: only explicitly allowed metadata may leave PatchPlane for Sentry.
  • Keep OpenTelemetry-compatible naming where practical.
  • Do not add an OpenTelemetry collector/backend for alpha.
  • Keep Sentry operational only; telemetry is never Patch Report evidence or provenance truth.

Tasks:

  • Define TelemetryService in core contracts.
  • Add Sentry plugin/layer for captured exceptions and failed operations.
  • Add traceId, workflowRunId, pluginName, operation, and runtimeSessionId fields consistently across future plugins.
  • Ensure Sentry traces/logs are operational visibility only, not provenance truth.
  • Capture server-function and initial GitHub webhook runtime failures through TelemetryService.captureError.
  • Centralize Effect-native telemetry annotations and failure capture helpers.
  • Add unit coverage for telemetry context helpers, Sentry no-DSN no-op behavior, and best-effort Sentry failure handling.
  • Manually validate a TelemetryService.captureError test event reaches Sentry.
  • Define and document a telemetry data classification and allowlist for identifiers, stage, status, provider, platform, counts, durations, and typed error codes in docs/telemetry-data-policy.md.
  • Add centralized, recursively bounded sanitization at every configured Sentry boundary using event, breadcrumb, log, metric, and span hooks; strip URL query/hash values and redact credentials, cookies, authorization data, OAuth codes, tokens, prompts, diffs, commands, stdout/stderr, webhook bodies, artifact contents, and provider response bodies. Shared hooks, explicit collection denial, request-body capture denial, and SDK transport-bound sentinel tests cover Effect, browser, and Cloudflare surfaces.
  • Stop forwarding raw Cause.pretty output or arbitrary exception/provider messages to Sentry; preserve full operational detail only in an explicitly safe local or durable evidence destination, and send fixed safe summaries plus bounded sanitized stack locations and attributes to Sentry.
  • Extend the provider-neutral telemetry contract with branded, bounded critical-path stage/status breadcrumbs, without importing Sentry into core.
  • Add explicit breadcrumbs for intake acceptance, attempt creation/claim, requirement persistence, sandbox lifecycle, candidate freeze, verification, review, policy, human decision, rerun, and publication claim/result transitions.
  • Wrap both source-control Worker entry points with request-scoped Cloudflare Sentry capture and flushing.
  • Capture actionable handled failures in rerun execution, runtime control, Patch Report assembly, decision publication, and canonical publication instead of relying on uncaught-exception capture or logs alone.
  • Classify expected validation, authorization, duplicate-delivery, and policy outcomes so they remain bounded diagnostics rather than noisy Sentry issues.
  • Attach searchable safe correlation metadata when known, including root/attempt workflow IDs, sandbox execution ID, candidate patch-set ID, decision/publication IDs, operation, and critical-path stage.
  • Attach environment and release/deployment identity to browser, Effect, and Cloudflare telemetry without exposing deployment credentials.
  • Add automated sentinel-secret tests proving events, logs, breadcrumbs, request URLs, and captured handled failures are sanitized before Sentry transport.
  • Run a deliberate non-sensitive deployed failure on each browser, Effect, client Worker, and source-control Worker surface and verify the correct Sentry project receives the issue with bounded breadcrumbs and correlation metadata.

Acceptance criteria:

  • Foundational browser, client Worker, server-function, and initial webhook failures have a Sentry capture path.
  • Every unexpected failure on the alpha critical path, including immutable rerun and canonical publication, creates one actionable Sentry issue or is linked to an already captured upstream issue.
  • A captured critical-path issue includes bounded stage breadcrumbs and safe correlation IDs sufficient to reconstruct the operational sequence without using Sentry as provenance truth.
  • Automated sentinel tests demonstrate that secrets, auth/session material, prompts, diffs, command/output content, webhook bodies, artifact content, provider response bodies, and URL query/hash values do not leave through Sentry events, logs, spans, or breadcrumbs.
  • Expected user, authorization, idempotency, policy, and evidence-incomplete outcomes do not create duplicate or high-noise error issues.
  • Browser, Effect, client Worker, and source-control Worker events identify the deployed environment/release and can be correlated by safe trace/workflow identifiers.
  • Product provenance remains in PatchPlane-owned storage/timeline records.
  • No OpenTelemetry collector, ClickHouse, or observability platform is required for alpha.

M8 — Daytona Sandbox Plugin

Status: In progress — Daytona Linux lifecycle/policy and R2-backed evidence capture are verified; the bounded alpha windows-small and Computer Use verification profiles remain open. The old Daytona-SDK-only live smoke has been removed in favor of PatchPlane-owned platform smokes.

Tasks:

  • Add DaytonaConfig with redacted API key handling.
  • Implement alpha-safe scoped sandbox execution via SandboxService.runRepositoryCommand / runRepositoryAgent.
  • Use ephemeral ordinary-execution profiles for alpha; Daytona persistence is the provider default, so stop/pause/archive are not cleanup.
  • Add explicit sandbox policy fields for lifecycle, resources, timeout, and network posture.
  • Implement checkout/clone support.
  • Implement command execution.
  • Collect command logs in workflow storage and upload large/raw evidence through the R2 artifact path.
  • Stop/destroy sandboxes on cancellation/failure where possible after acquisition succeeds.
  • Require every completed execution group to poll explicit deletion to not-found; ephemeral or auto-delete behavior is defense in depth, and stopped/paused/archived is not deleted.
  • Persist bounded ownership, reason, deadline, reconciliation state, and eventual deletion evidence for the RPC sessions intentionally retained after acquisition.
  • Reject verification profiles that create snapshots/forks, mount writable volumes/external storage, pause/archive for reuse, or otherwise derive persistent candidate-controlled state.
  • Add live Daytona smoke script with redacted API-key handling, public repository clone, command execution, and cleanup polling.
  • Persist normalized sandbox policy as typed Convex metadata rather than JSON glue.
  • Add safe fake Daytona lifecycle tests for clone failure, command failure, non-zero exit, interruption, retain mode, and delete retry.
  • Add a trusted Daytona platform/snapshot selector that maps the bounded Windows requirement to windows-small without accepting arbitrary browser or candidate-controlled snapshot names.
  • Reuse Daytona exact-commitId Git clone on Windows; decode provider Git status/history through PatchPlane-owned schemas to prove clean detached checkout and exact head, without treating status as a candidate digest.
  • Replace remaining POSIX-only candidate/evidence probes with a PowerShell-compatible Windows path for architecture, cleanup, diff hashing, bounded artifact capture, and command execution.
  • Persist the resolved Daytona sandbox class/snapshot, runtime boundary, operating system, architecture, effective resource limits, network tier/policy/exceptions, command identity, candidate digest before/after, and cleanup outcome.
  • Reject public previews, linked sandboxes, writable shared volumes, and undisclosed snapshot/fork reuse in alpha verification profiles.
  • Add a bounded execution-group scheduler with per-attempt/global sandbox limits, command/session timeout budgets, cancellation, and typed Daytona rate/capacity outcomes; exhausted provider capacity is not a repository test failure.
  • Forbid runtime resource resizing during verification, record snapshot-inherited effective resources, and disclose when concurrent sessions share one sandbox filesystem/network.
  • Terminate or invalidate every background/session command before an execution group completes; command completion must not leave untracked work running.
  • Add credentialed isolation/persistence/scale smokes that verify representative allowed/denied egress, authenticated-only ingress, effective limits, absence of linked/shared/derived state, bounded rate-limit behavior, retained-RPC reconciliation, and delete-to-not-found cleanup; requested configuration alone is not enforcement evidence.
  • Add automated Windows adapter tests and a credentialed windows-small smoke that proves exact-commit clone, validated status/head, requirement execution, evidence readback, digest coherence, and deletion.
  • Add a PatchPlane-owned Daytona Computer Use adapter that starts and stops the desktop processes, bounds mouse/keyboard/display operations, and captures screenshots or recordings as untrusted candidate-bound artifacts.
  • Add Linux and Windows Computer Use lifecycle tests plus a credentialed browser/GUI smoke that proves process status, artifact readback and hashing, failure behavior, and sandbox deletion.

Implementation note:

  • M8 currently includes the pragmatic daytona-pi command adapter: Daytona provisions the sandbox and invokes the Pi CLI inside it. This is the alpha bridge, not the final RuntimeService split. The web/control-plane runtime must not load the in-process Pi SDK plugin for this path.

Acceptance criteria:

  • A workflow can provision a sandbox, check out a GitHub repository ref, run at least one command, collect command logs, and tear down the sandbox.
  • Sandboxes never receive long-lived WorkOS, Convex, or GitHub App credentials.
  • Requested sandbox lifecycle and network policy are visible in stored workflow metadata.
  • Effective isolation evidence records the runtime boundary, inherited/effective resource limits, network tier/exceptions, forbidden sharing/ingress/persistence posture, representative enforcement behavior, bounded concurrency/capacity outcome, and delete-to-not-found result.
  • Durable raw artifact capture is backed by R2 rather than Convex stdout/stderr columns.
  • A required Windows check can run in Daytona windows-small with candidate-bound evidence and final sandbox deletion.
  • A required browser/GUI check can run through Daytona Computer Use on Linux or Windows and produce bounded candidate-bound visual evidence.
  • A required macOS check remains explicitly blocked and cannot produce a clean policy result.
  • A production-dependent requirement either resolves to an explicitly trusted secret-free equivalent or remains blocked without receiving production credentials.

M8.25 — Minimal Cloudflare infra provisioning

Status: Complete for minimal alpha R2 + AI Gateway provisioning and runtime binding composition

Purpose:

Add the smallest Cloudflare-first infrastructure slice needed for evidence storage and model access without turning PatchPlane into an infrastructure platform.

Scope:

  • Add apps/infra as a runnable Alchemy deployment app.
  • Provision PatchPlane-owned Cloudflare R2 buckets for dev/prod stages.
  • Provision PatchPlane-owned Cloudflare AI Gateway for agent model access.
  • Add lifecycle rules for short-lived alpha artifacts where useful.
  • Expose required environment/config values for runtime plugins.

Explicit non-goals:

  • Do not move runtime execution to Cloudflare Workers for alpha.
  • Do not replace Octokit/GitHub App runtime integration.
  • Do not manage customer repositories as Alchemy resources.
  • Do not add Cloudflare Queues, Workflows, Vectorize, AutoRAG, or broader Cloudflare platform scope for alpha.

Tasks:

  • Add apps/infra/alchemy.run.ts.
  • Add dev/prod stage naming for PatchPlane-owned infrastructure.
  • Provision R2 bucket(s) for evidence artifacts.
  • Provision AI Gateway for Pi model access.
  • Document required env vars and generated config values.
  • Add deployment scripts for local/CI usage.

Acceptance criteria:

  • Running the infra deployment for a dev stage creates the R2 bucket and AI Gateway.
    • Verified with CI=1 bun run infra:deploy -- --env-file ../../.env.local --stage dev --yes.
    • Created patchplane-dev-evidence-artifacts and patchplane-dev-model-gateway.
  • PatchPlane runtime code does not import Alchemy.
  • packages/core imports no Alchemy or Cloudflare SDK types.

M8.5 — Alpha Workflow Visibility Slice

Status: Implemented for the current Convex workflow read model and R2-backed evidence links

Scope:

  • Make the trust loop visible early, before a polished dashboard.
  • Use simple tables, cards, and vertical timelines.
  • Show workflow status, source, repository, sandbox state, runtime state, artifact references when present, and decision state.

Tasks:

  • Add workflow detail view or side panel.
  • Show prompt/intake summary.
  • Show repository and sandbox status.
  • Show command/log placeholders backed by real records where available.
  • Show provenance timeline events.
  • Keep complex graph UI deferred.
  • Use TanStack Table with the shared table primitive for the workflow queue.
  • Use TanStack Form with Effect Standard Schema validation for workflow-start input.
  • Add direct M8.5 hardening coverage for workflow queue filtering/selection and workflow-start form validation.

Acceptance criteria:

  • A real GitHub/Daytona-backed workflow is understandable from the UI without reading server logs.
  • The UI communicates why a patch is still untrusted, pending review, approved, or rejected.

Evidence:

  • Authenticated /app now renders a workflow review console instead of dashboard cards.
  • Auth loading uses the same workflow-console skeleton instead of the old metric-card dashboard.
  • The console shows workflow status, source/repository, trust state, selected workflow inspector, sandbox/log/decision evidence, detail tabs, timeline, and artifact-reference state.
  • The selected queue row and inspector share the same detail-backed trust state, so sandbox failure is not hidden behind a generic reviewed/needs-review row.
  • Workflow rows open an object-specific detail sheet directly while keeping the selected inspector state in sync.
  • Convex workflowStarts.getDetail returns prompt, workflow run, a bounded recent runtime-event projection, and sandbox executions for the detail surface; full raw runtime output remains R2 evidence so noisy Pi deltas cannot freeze the client.
  • apps/client/src/components/app-shell/workflow-console.test.tsx covers queue rendering, search/trust-state filtering, inspector evidence, row-open behavior, detail tabs, and artifact-reference display.
  • apps/client/src/components/app-shell/start-workflow-panel.test.tsx covers TanStack Form submission behavior, authenticated-workspace gating, and Effect Standard Schema validation blocking invalid prompts.
  • apps/client/src/components/app-shell/loading-workflow-console.test.tsx guards against the old metric-card loading dashboard returning.

M8.6 — Hosted GitHub Repo Connection Slice

Status: In progress — implementation, latest-verification aggregation, and provider-level live smoke are complete; browser acceptance remains open

Goal: Make the hosted PatchPlane alpha usable without CLI setup and without asking users to manually install/configure their own GitHub App.

User-facing flow:

  1. User signs in to PatchPlane.
  2. User clicks "Connect GitHub".
  3. GitHub shows the standard account/org and repository access screen.
  4. User selects one or more repositories.
  5. PatchPlane stores the GitHub installation/account/repository mapping.
  6. Dashboard shows connected repositories and connection status.
  7. Developer opens or updates a PR.
  8. PatchPlane receives the PR event.
  9. PatchPlane runs verification.
  10. PatchPlane posts a trust report as a PR comment.
  11. Dashboard shows the run result, logs, and decision state.

Implementation notes:

  • Hosted PatchPlane uses a PatchPlane-owned GitHub App.
  • Use Octokit for GitHub App authentication, installation access tokens, webhook handling, repository listing, PR comments, and check/status updates.
  • Users should not see GitHub App terminology unless GitHub itself displays it during authorization.
  • Store installation ID, account/org ID, selected repositories, and permission state.
  • Treat missing repo access as a reconnect/configuration issue, not a developer setup task.

Completed implementation:

  • Added provider-owned repository connection domain schemas in packages/domain/src/repository-connection.ts.
  • Added Convex connectedRepositoryAccounts, connectedRepositories, and githubConnectionIntents tables with indexes for workspace listing, pending install state, and GitHub webhook routing.
  • Added authenticated Convex repository connection mutations/queries plus system-secret webhook route lookup in packages/backend/convex/connectedRepositories.ts.
  • Extended SourceControlService with installation account and installation repository listing contracts.
  • Implemented GitHub App installation account/repository listing in GitHubProviderPlugin via Octokit installation auth, including API failure and malformed metadata coverage.
  • Added normalized pull_request.opened and pull_request.synchronize event support with PR provenance fields.
  • Added /api/github/install/start to create a pending connection intent and redirect to the GitHub App installation URL.
  • Added /api/github/install/callback to consume the install intent, list installation repositories, and store connected repositories in Convex.
  • Added connected GitHub repository UI in the authenticated app shell with a Connect GitHub button and connected repository status list.
  • Aggregated each connected repository's latest workspace-scoped verification run and decision status, with a direct workflow-detail link and browser readback assertion.
  • Updated /api/github/webhook to route hosted webhooks through Convex connected repository lookup, while preserving the env allowlist fallback for OSS/local self-hosted routing.
  • PR opened/synchronize events now start the existing verification path and publish the sandbox trust report through the existing GitHub issue-comment publication path.
  • Added tests for Convex repository connection storage/routing/intents, PR webhook normalization/intake mapping, PR trust-report publication, Octokit installation listing/failures, install flow helpers, and webhook route workspace resolution.
  • Live-smoked hosted GitHub App install/callback against a real selected repository, storing the installation account and selected repository in Convex.
  • Live-smoked PR synchronize webhook routing through Convex connected repository lookup, Daytona/Pi sandbox execution, Convex sandboxExecutions persistence, and GitHub PR trust-report comment publication.
  • Added a PatchPlane bot-comment feedback-loop guard for generated trust-report comments.
  • Live-smoked the direct Convex-backed Daytona/Pi path from StartWorkflowFromIntake through workflowStarts:createFromExternalIntake, RunSandboxAgentForWorkflow, and workflowStarts:recordSandboxExecution.

Remaining hardening:

  • Add a reusable smoke:convex-sandbox script for the deployed GitHub → Convex → Daytona/Pi path instead of relying on an inline command.
  • Add browser E2E for Connect GitHub once stable hosted credentials are available.
  • Add richer dashboard aggregation for latest verification status per connected repository.

Acceptance criteria:

  • No CLI required for hosted onboarding.
  • No manual GitHub App creation required.
  • No webhook URL copy/paste required.
  • User can connect GitHub through PatchPlane in the release-candidate browser acceptance flow.
  • User can select repositories on GitHub's screens in the release-candidate browser acceptance flow.
  • PatchPlane can list connected repositories.
  • PatchPlane reacts to PR opened/synchronize events.
  • PatchPlane posts a clear PR trust report.
  • Dashboard shows connected repo, latest verification run, and status.

Goal:

Hosted:
Sign in → Connect GitHub → Select repo on GitHub screen → Open PR → PatchPlane verifies → PR trust report + dashboard run

OSS:
CLI/self-host setup → configure GitHub/App manually if needed → run PatchPlane locally/self-hosted

M9 — Remote Sandbox Agent Runtime Adapter

Status: Complete for the alpha runtime architecture — Pi JSON-mode and RPC-mode paths are sandbox-backed, Effect-native at the runtime boundary, unit-tested, and live-smoked against Daytona. Remaining future work is provider breadth and deeper long-running session reconciliation hardening, not a blocking architecture gap.

Intent:

PatchPlane does not run coding-agent runtimes in-process in the trusted control plane. Pi executes only inside remote sandbox environments. The control plane provisions the sandbox, launches the runtime process, captures untrusted output/events, normalizes them into PatchPlane schemas, and persists them through Convex/R2.

Tasks:

  • Add initial Pi provider/model defaults for the sandbox-backed CLI path.
  • Prove Pi can be invoked inside Daytona through the M8 daytona-pi command adapter.
  • Remove the unused in-process Pi SDK plugin from packages/plugins exports/registry/dependencies.
  • Remove the leftover packages/plugins/src/pi config shim and unused premature core RuntimeService/ModelGatewayService abstractions.
  • Move Pi command construction, provider env mapping, and output parsing out of the Daytona plugin into sandbox-backed runtime adapter modules.
  • Replace the legacy runtime/pi/rpc.ts helper facade with an Effect RPC contract (contract.ts), runtime-session facade (runtime-session.ts), transport adapter (transport.ts), stream JSONL decoder (jsonl.ts), protocol parser (protocol.ts), and normalized event stream (ingestion.ts).
  • Use pi --mode json or pi --mode rpc for structured runtime output where practical.
  • Replace OpenAI-only runtime assumptions with configurable provider/model settings.
  • Default alpha model access to Cloudflare AI Gateway where configured.
  • Keep direct OpenAI or other direct providers as local/debug fallback options.
  • Map Pi events to PatchPlane RuntimeEvent records.
  • Map cancellation to remote sandbox process/session control.
  • Map steering/follow-up to human interrupt/redirect primitives only when the remote sandbox runtime mode supports it.
  • Persist RuntimeSession lifecycle state in Convex for RPC-capable remote runtime sessions.
  • Persist RPC runtime sessions immediately after Daytona returns sessionId/commandId, before sending control input.
  • Add unit coverage for Pi RPC command encoding/parsing, Daytona async session handles, control workflows, hard-terminate idempotency, and Convex runtime session lifecycle.
  • Add a Pi-specific strict LF JSONL stream decoder that preserves standalone \r, U+2028, and U+2029 instead of relying on generic line splitting.
  • Wrap Daytona streaming log callbacks as typed Effect Streams and feed them through the Pi runtime-session event stream for incremental event persistence.
  • Preserve enough raw event metadata for debugging while storing normalized events as product truth.
  • Expose abort/steer/follow-up/terminate through authenticated hosted app/API surfaces with workflow-run authorization checks; client input is workflowRunId plus operation/message, never raw sandbox/session IDs.
  • Integrate Daytona log streaming/polling into incremental runtime-event persistence for active RPC sessions, including disconnect reconciliation via buffered logs and idempotent Convex dedupe.
  • Add a reusable Daytona/Pi RPC smoke script entrypoint with RPC event collection and steer/follow-up/abort/terminate assertions.
  • Run the live Daytona/Pi RPC smoke against real credentials and validate get_state, command responses, streamed runtime events, steer/follow-up acceptance, abort, terminate/delete-session behavior, and final Daytona sandbox deletion.
  • Add architecture coverage preventing Pi runtime packages from becoming trusted control-plane dependencies.

Acceptance criteria:

  • PatchPlane can start one Pi coding-agent session inside a remote sandbox-backed workflow.
  • The hosted web/control-plane Worker does not bundle @earendil-works/pi-coding-agent, @earendil-works/pi-ai, or provider SDKs solely for agent runtime execution.
  • Pi uses configured provider/model access rather than a hardcoded single provider.
  • Pi events are normalized into PatchPlane-owned RuntimeEvent records through an Effect Stream boundary.
  • Pi-specific runtime objects and raw JSONL commands do not cross into core/UI.
  • Daytona plugin code consumes makePiRuntimeSession rather than raw push/end parser state or legacy command helper functions.

M9.5 — Dashboard and workflow visibility pass

Status: In progress — M8.5 sheet detail is being split into queue/inspector triage plus a full workflow investigation route

Timing:

  • Before GitHub/Daytona/Pi: keep the UI functional, not polished.
  • After GitHub and Daytona: add real repository, sandbox, command/log, and provenance placeholders.
  • After Pi events: add the first serious dashboard/review UX pass.

Rules:

  • Do not fork full dashboard starters or replace the current app shell.
  • Build from local UI components in apps/client/src/components/ui.
  • Keep complex provenance graph UI deferred.
  • Make raw patch/diff, logs, artifacts, and provenance easy to inspect.
  • Use the sheet only as quick preview/triage; serious investigation belongs on the full workflow page.

First dashboard scope:

  • Recent workflows table exists from M8.5 and remains the queue surface.
  • Right inspector exists from M8.5 and remains the fast triage surface.
  • Add full workflow detail route for investigation (/app/workflows/$workflowRunId).
  • Keep sheet as compact preview with an “Open full workflow” handoff.
  • Timeline with runtime/sandbox/provenance events.
  • Runtime session section backed by Convex runtimeSessions read-model data.
  • Full-page logs, sandbox evidence, artifacts, review, and raw evidence tabs.
  • Review split view once candidate patches exist.
  • Approve/reject/request-changes controls with required comment UI.
  • Persist minimal review decisions and durable review-run data through the M10 storage model.

Acceptance criteria:

  • The dashboard uses the existing PatchPlane shell.
  • A real Pi/Daytona/GitHub-backed workflow is understandable from the UI.
  • Review ergonomics are good enough for maintainer-controlled dogfooding.

M9.75 — Patch Report and evidence capture slice

Status: In progress — Patch Report V1 and sandbox-generated candidate foundations exist, but exact incoming-PR freeze and read-only review remain missing

Purpose:

Make the Patch Report the center of the alpha. Capture enough candidate-bound evidence to help a developer trust or reject the exact incoming PR patch.

Scope:

  • Add PatchReport domain/read-model schema.
  • Assemble Patch Report V1 for one immutable attempt and candidate from durable workflow, execution, verification, review, policy, decision, artifact, and publication records.
  • Publish Patch Report summary to GitHub.
  • Add EvidenceArtifact domain model and Convex metadata persistence.
  • Add ArtifactsService with Cloudflare R2 implementation.
  • Store large/raw artifacts in R2, not Convex, Sentry, or PostHog.
  • Add one minimal browser verification path with screenshot or video evidence where useful.

Tasks:

  • Define initial PatchReport schema.
  • Assemble Patch Report V1 from candidate-correlated durable records and reject legacy projection.
  • Publish the canonical Patch Report V1 through the decision publication path; sandbox completion remains an execution update, not a verification verdict.
  • Persist trusted verification requirements before execution and candidate-bound verification results afterward.
  • Freeze sandbox-generated candidates with producing execution, pinned base SHA, and exact diff digest before verification; this remains implementation foundation only.
  • Freeze the alpha incoming PR candidate before execution with repository/PR identity, webhook-authenticated base/head SHAs, exact diff artifact, and digest.
  • Detect candidate mutation across verification and fail closed.
  • Separate read-only review from generation so Pi cannot change the frozen alpha candidate.
  • Replace the one-sandbox-per-attempt persistence guard with one orchestration claim plus bounded, idempotent execution-group claims for required Linux, Windows, and Computer Use environments.
  • Define EvidenceArtifact schema.
  • Define ArtifactsService interface.
  • Implement R2-backed ArtifactsService plugin.
  • Store artifact metadata and hashes in Convex.
  • Add signed or authenticated artifact access path.
  • Capture stdout/stderr logs as artifacts where size warrants it.
  • Capture patch/diff/test-report artifacts.
  • Add first browser verification result and screenshot/video artifact path.

Implementation evidence:

  • Daytona records the clone base SHA and captures git diff --binary against that base, including staged, committed, unstaged, and untracked worktree changes.
  • Daytona probes conventional test report files such as .patchplane/test-report.json and .patchplane/test-report.xml after the main run and optional producer command.
  • Daytona probes conventional browser screenshot files such as .patchplane/browser-screenshot.png after the main run and optional producer command.
  • Configured test and browser requirements are stored before execution. Their results retain explicit passed/failed/blocked/error outcomes, candidate digests, environment metadata, and artifact references; missing or mismatched required evidence remains incomplete.
  • Core uploads sandbox-provided evidence through CaptureEvidenceArtifact, which stores raw bytes in R2 and metadata in Convex.
  • The client Evidence tab opens persisted evidence artifacts through authenticated signed URLs.

Acceptance criteria:

  • A developer can open one candidate-bound Patch Report and answer: what was requested, which attempt/candidate is shown, what ran, where it ran, what independently passed or failed, what is missing, what evidence exists, and what decision is pending or recorded.
  • Pi exit 0, candidate capture, external review, independent verification, policy, human decision, and publication remain separate states.
  • A fresh credentialed dogfood run demonstrates candidate-bound evidence; until then M9.75 is not a release-complete claim.
  • A workflow stores raw evidence artifacts in R2.
  • Convex stores artifact metadata, hashes, and references.
  • The UI can link from a Patch Report/provenance event to its evidence artifacts.
  • Raw artifacts are not sent to PostHog and are not treated as Sentry product truth.

M9.9 — Minimal Landing Page Packaging Slice

Status: Complete for the public alpha packaging slice

Purpose:

Make the public product message understandable before broader alpha demos.

Scope:

  • Keep language product-focused and developer-facing.
  • Avoid heavy architecture-first copy.
  • Explain the trust loop clearly.
  • Link to the OSS repo/docs.
  • Avoid pricing/commercial details in OSS docs.

Minimal sections:

  • Hero: explain the pain and outcome in one sentence.
  • Problem: show why AI-generated changes need evidence before trust.
  • Review flow: capture → isolated verification → evidence → human decision → GitHub result.
  • Trust report preview: show product states without fictional commands or unsupported capability claims.
  • Open-source alpha: state the focused GitHub workflow without putting provider or architecture details on the landing page.
  • OSS/developer links: current capabilities, quick start, contributing, and roadmap.

Acceptance criteria:

  • A developer can understand the alpha promise quickly.
  • The landing page does not overpromise broad platform capabilities before alpha proof.
  • English and German landing copy has matching keys and product intent.
  • Client tests and the production client build pass after a frozen-lockfile dependency refresh.

M10 — Evidence-backed decision and publication loop

Status: In progress; V1 semantics are implemented locally, but a fresh authenticated dogfood run, rerun, and canonical publication replay remain open

Purpose:

A human can approve, reject, or request changes from the Patch Report, and PatchPlane can publish the resulting GitHub outcome without treating the AI patch as trusted before the recorded decision.

Tasks:

  • Implement CandidatePatchSet schema and persistence.
  • Implement ReviewRun and ReviewFinding schemas and persistence.
  • Implement one reviewer path, initially test/lint-oriented.
  • Implement PolicyService.evaluatePolicy.
  • Implement ProposeMergeDecision.
  • Persist human decisions against the exact execution/candidate/review/policy projection, requiring an explicit override reason when verification is incomplete.
  • Require a comment for approve/reject/request-changes decisions.
  • Derive independent execution, candidate, verification, review, policy, human-decision, publication, and aggregate trust states.
  • Add operator approval/rejection/request-changes path.
  • Update one canonical GitHub issue comment and candidate-headSha check result after decision; never fall back to a base SHA, newer head, or unrelated generated candidate.
  • Supersede preliminary sandbox-result comments so one canonical exact-head Patch Report represents the attempt.
  • Record workflow-scoped provenance for prompt/actor/workspace/repository, sandbox/runtime activity, commands/tests, candidate patch, review/policy result, human decision, and publication result.
  • Keep Patch Report as a deterministic projection over durable workflow, evidence, review, decision, publication, and provenance records; avoid a second stale snapshot truth.
  • Implement immutable rerun lineage with reason/idempotency, atomic execution claims, and authoritative rerun dispatch.
  • Add replay-safe identities for review runs, findings, policy decisions, human decisions, and publication records.
  • Revalidate the complete deployed V1 trust loop, immutable rerun, human override behavior, and canonical publication replay against one real repository.

Implementation evidence:

  • Domain schemas now cover CandidatePatchSet, ReviewRun, ReviewFinding, PolicyDecision, HumanDecision, and PublicationResult.
  • Convex persists those records with workflow-run indexes and returns them from workflow detail.
  • System-ingestion mutations record candidate patches, automated review/policy output, and publication results.
  • Authenticated human decisions require a non-empty comment and decision:approve or decision:reject permission.
  • Core now has ReviewService, PolicyService, alpha deterministic review/policy layers, and ProposeMergeDecision.
  • Policy evaluates a coherent candidate-bound evidence snapshot, stores its version and SHA-256 input digest, and fails closed on missing, blocked, errored, stale, mutated, platform-unavailable, or mismatched requirements.
  • Patch Report V1 selects decisions only when their execution, candidate, review, and policy IDs match the displayed projection; it does not use an independent latest-decision shortcut.
  • Maintainers and operators can approve, reject, or request changes through the authenticated UI/server path with a required comment and replay-safe decision idempotency key.
  • Decision publication uses a leased atomic dispatch claim, durable pending/result records, stable root-workflow comment markers, and candidate check-run external_id values so concurrent/replayed publication does not duplicate GitHub output.
  • Aggregate publication provenance can transition from failed to succeeded after retry while retaining links to all publication result records.
  • A system-secret acceptance snapshot exposes only workflow statuses, evidence hashes, publication IDs, and aggregate counts for live verification without bypassing WorkOS authorization on full workflow detail.

Current validation:

  • Domain, core, plugin, backend, architecture, and webhook suites pass with the durable decision/publication changes.
  • Plugin tests cover the clone-base diff command; a local Git probe confirmed it captures staged, committed, unstaged, and untracked candidate changes.
  • GitHub adapter tests verify retry reconciliation for both issue comments and check runs.
  • The 2026-07-10 Convex deployment was refreshed after CLI authentication. The hosted smoke then completed GitHub intake, Daytona/Pi JSON execution, runtime-event persistence, R2 evidence capture, sandbox-generated candidate capture, automated review, policy evaluation, provenance persistence, and Patch Report publication for workflow ms75nyt9d572v6p7ab98vrq7158a8kgx on test PR 96. This proves plumbing, not exact incoming-PR verification.
  • GitHub API readback confirmed the workflow-specific Patch Report comment. The dedicated Daytona/Pi RPC smoke separately verifies runtime-session persistence because hosted JSON-mode executions intentionally have no RPC session.
  • A final deployed WorkOS-authenticated human-decision-to-GitHub run and publication replay against that workflow remain required before marking M10 complete.

Acceptance criteria:

  • An exact incoming PR candidate remains untrusted until all declared required candidate-bound verification passes, policy accepts the coherent snapshot, and human review completes; approval with incomplete verification is visibly approved-with-override and requires a reason.
  • A human can approve, reject, request changes, or create an immutable reasoned rerun from the Patch Report before publication/merge handoff.
  • The alpha demo can show why the decision was made using persisted Patch Report provenance and evidence, not only transient logs.

M10.5 — Optional SQL durable workflow storage plugins

Status: Deferred until after the independent pre-merge trust-boundary demo has real workflow/event shapes

Scope:

SQL plugins are for durable workflow persistence only. They are not intended to replace Convex's realtime UI/read-model role, WorkOS auth mirroring, or Convex-side public query/mutation authorization in the alpha.

Potential future targets:

  • Postgres via Effect SQL
  • SQLite Node for local/self-hosted deployments
  • MySQL after schema portability is proven

Tasks:

  • Extract shared SQL workflow-storage implementation when real workflow event shapes stabilize.
  • Add migrations for workflow and event tables.
  • Keep all SQL driver details inside plugin packages.

Acceptance criteria:

  • A SQL plugin can implement the StorageService workflow-start methods without changing packages/core.
  • SQL plugin failures map to PatchPlane StorageError.
  • Convex can remain enabled for realtime UI projection even when durable persistence is SQL-backed.

M11 — Dogfood on a maintainer-controlled repository

Status: Planned after exact incoming-PR identity and execution closure

Tasks:

  • Connect a PatchPlane-owned or maintainer-controlled repository through the GitHub plugin.
  • Run at least three real incoming PR candidates through PatchPlane without asking Pi to rewrite them.
  • Use PR 128 to prove the truthful incomplete/override path for its required macOS check, and use a supported-platform design-partner PR to prove a fully passed exact-candidate path.
  • Capture friction in setup, sandbox lifecycle, event readability, artifact usefulness, review usefulness, and approval ergonomics.
  • Convert dogfood findings into follow-up issues before broader launch.

Acceptance criteria:

  • At least one exact incoming PR candidate is frozen, sandboxed, verified, reviewed, decided, and published through the PatchPlane loop.
  • The report never labels Pi completion, raw JSONL, hosted CI, or an unrelated smoke candidate as verification of the incoming PR.
  • The demo path is reproducible without manually editing database state.
  • The workflow is good enough to demonstrate publicly.

7. Cross-cutting work

Config

  • Convex, WorkOS, and GitHub plugin config load through Effect Config.
  • Secrets are redacted where supported.
  • Add static plugin metadata registry with env requirements/defaults.
  • Add local CLI support for plugin listing, env template/check, doctor, and init.
  • Use root patchplane.config.json as CLI-managed non-secret project config.
  • Add Cloudflare R2 config to plugin metadata.
  • Add Cloudflare AI Gateway config to plugin metadata.
  • Add fail-closed startup/config preflight for trust-loop and Convex/Daytona live smokes before provider work begins.
  • Add a bundle-boundary regression check that the hosted web app does not include the in-process Pi SDK runtime.
  • Add a Daytona Pi smoke/eval that runs pi --mode rpc in a sandbox and validates parseable normalized runtime output.

Observability

  • Add structured context fields for the foundation path.
  • Add initial Effect log spans for the foundation path.
  • Add consistent runtimeSessionId, pluginName, and operation fields across runtime/sandbox/artifact plugins.
  • Add Sentry-backed TelemetryService plugin.
  • Add OTLP export only when a real collector/backend is introduced.
  • Keep ClickHouse deferred until high-volume trace analytics become necessary.

Analytics

  • Add minimal AnalyticsService interface.
  • Add PostHog product events for alpha usage only.
  • Track basic activation/usage events such as workflow started, trust report viewed, patch approved, patch rejected, and artifact opened.
  • Do not send raw code, raw diffs, prompts, secrets, or raw evidence artifacts to analytics by default.

Artifacts

  • Define EvidenceArtifact domain schema.
  • Store raw artifacts in Cloudflare R2.
  • Store artifact metadata, hashes, and references in Convex.
  • Add authenticated/signed access to artifact downloads.
  • Add retention/lifecycle policy for alpha artifacts where useful.

Testing

Milestone acceptance criteria and their executable evidence are tracked in docs/acceptance-tests.md. A checked roadmap item does not by itself mean that a credentialed live acceptance path has passed for the current release candidate.

  • Foundation core/domain/plugin tests pass.
  • Backend Convex tests cover authenticated and external-ingestion paths.
  • GitHub plugin tests cover repository access, comments, and webhook signatures.
  • CLI integration tests cover command parsing, init, env, plugin validation, and doctor failures.
  • Add Daytona sandbox plugin tests with safe mocks/fakes.
  • Add R2 artifact plugin tests.
  • Add Pi runtime event normalization tests.
  • Fail CI when a roadmap milestone claims completion while its acceptance matrix still contains a Missing row.
  • Add true external browser/AuthKit/Convex E2E once stable test credentials exist. An opt-in headed Playwright acceptance helper now encodes the real AuthKit and Connect GitHub flow without placing credentials in CI.

Security

  • GitHub webhook signatures are verified before ingestion.
  • User-facing workflow starts require WorkOS JWT validation and mirrored permission checks.
  • Convex reads require WorkOS identity and mirrored membership permissions.
  • No long-lived credentials in sandboxes.
  • Treat every runtime-produced patch and artifact as untrusted until sandbox review and approval complete.
  • Sandbox profiles have explicit network and lifecycle policy.
  • Artifact access is authenticated or signed.
  • Replace shared-secret ingestion with HMAC or equivalent request signing before production exposure if needed.
  • Add resource-scoped authorization when repository/project resources are introduced.

8. Public non-goals for alpha

Do not implement before the first trust-boundary demo is complete:

  • multiple sandbox providers beyond Daytona
  • multiple Git forges beyond GitHub
  • Git replacement or hosted forge behavior
  • semantic merge/conflict resolution
  • generalized enterprise policy editor
  • broad plugin marketplace
  • billing or monetization surfaces
  • full ClickHouse trace analytics
  • OpenTelemetry collector/backend
  • PostHog AI observability product dashboards
  • complex provenance graph UI
  • autonomous merge without explicit policy/human control

9. Working rule

When implementation and spec disagree:

  1. Check current package/vendor documentation and implementation behavior.
  2. Update SPEC.md if the product boundary, trust model, or architecture boundary changes.
  3. Update this ROADMAP.md if milestone order, task status, acceptance criteria, or implementation evidence changes.
  4. Keep SDK-specific knowledge inside plugins and app composition code, never in core.
  5. Keep public docs focused on product and engineering direction; keep commercial strategy, customer notes, and private operations outside the OSS repo.