IDKMesh

ADR-0013 — GitHub-First, Server-Optional Deployment

Status: Proposed for adoption
Date: 2026-09-22

Context

IDKMesh is intended to coordinate humans, coding agents, model providers, deterministic tools, verifiers, and optional external compute around a Git repository without collapsing implementation, verification, and integration authority.

The repository already has:

The remaining deployment question is whether every adopting project must operate a permanent IDKMesh service/database, or whether the first useful product can run primarily from the target GitHub repository.

Introducing an always-on server too early would increase onboarding, security, operations, tenancy, authentication, persistence, and deployment complexity before evidence shows those costs are necessary.

GitHub already provides several control-plane primitives useful to IDKMesh:

Decision

Adopt GitHub-first, server-optional as the default deployment architecture for the first productized external-project profile.

The default profile, named G0, is:

GitHub repository
  + .idkmesh project/policy/config
  + Issues / labels / optional Projects
  + GitHub Actions event-driven coordination
  + PRs / Checks / reviews
  + compact durable Git-native run/evidence ledger
  + protected main
  + hosted agent/model connectors

No project-owned always-on IDKMesh server is required in G0.

Hosted agents execute on provider infrastructure. Optional local/volunteer/project machines may run idkmesh-node as workers, but those machines are not the central source of coordination truth.

GitHub remains canonical for code and integration authority.

Required invariants

  1. Worker success is not acceptance.
  2. Verification recommendation is not merge authority.
  3. GitHub Actions is an execution substrate, not the only durable database.
  4. Ephemeral workflow runners must be restart-safe.
  5. Duplicate/replayed GitHub events must not create duplicate external work.
  6. Issue/comment/Project text is untrusted input and cannot grant secrets, executable authority, network/filesystem expansion, repository-admin authority, or merge authority.
  7. Secret values never enter tracked project configuration.
  8. Default workflow permissions are least privilege.
  9. A higher-capability model does not gain higher repository authority.
  10. Optional GitHub features must fail additively: disabling Projects, Pages, artifact attestations, or OIDC must not destroy the core WorkUnit -> candidate -> verify -> human integration path.

Deployment profiles

G0 — GitHub repository control plane

Primary target. No always-on IDKMesh service.

Use for:

G1 — GitHub + optional nodes

G0 plus one or more idkmesh-node workers for:

The durable control state still remains outside individual nodes.

G2 — GitHub + lightweight authenticated control service

Add only when real usage demonstrates a requirement such as:

G2 may use SQLite for a single deployment or Postgres for shared/multi-user deployment. GitHub remains canonical for source and integration.

G3 — shared multi-project control plane

For organizations managing many repositories/installations. Requires explicit tenancy, authentication/authorization, audit, rate limits, database migration strategy, and GitHub App installation boundaries.

G4 — federated mesh

Long-term research only. It must not complicate G0 adoption.

GitHub-native capability policy

Required for G0 implementation

Optional/additive

None of these optional capabilities may become an implicit correctness or acceptance authority.

Persistence decision

Do not rely on:

G0 must have a compact durable ledger containing sufficient metadata/digests to reconstruct run state after workflow termination.

Large logs may remain in Actions/provider storage if the ledger retains stable references/digests and enough canonical evidence for later interpretation.

The exact storage representation is defined by the GitHub-first operations specification, not this ADR.

Multi-user identity decision

GitHub identity is the bootstrap human identity provider for G0/G1.

Do not create a separate IDKMesh username/password system for the first product.

Project policy distinguishes stage-specific capabilities such as:

A person may hold several roles where policy permits, but the system records the actor and stage independently.

Security consequences

Positive

Risks

These are accepted for G0 and become revisit triggers for G2/G3.

Alternatives considered

A. Mandatory central server from first install

Rejected for the first product. It creates deployment/auth/database/tenancy/operations burden before a second-project pilot proves it is necessary.

B. Store all state only in GitHub issue comments and Actions artifacts

Rejected. Comments are poor machine-state primitives and Actions artifacts are not an adequate sole durable authority surface.

C. Local-only coordinator on a maintainer laptop

Rejected as the default. It creates a hidden single-machine dependency and weakens multi-user/restart semantics. Local mode can remain a development/testing option.

D. GitHub-first with optional service escalation

Chosen.

Acceptance evidence required before calling G0 proven

The no-server second-project pilot must demonstrate:

If the pilot exposes an unmet requirement, record that evidence before promoting G2 into the default installation.

Implementation references

Revisit conditions

Revisit this ADR when any of these are measured:

Until one of those conditions is demonstrated, a server remains optional.

This site is open source. Improve this page.