Proposal: foundational workspace-runtime-contract spec (descriptive-first, no code)

[jonesrussell]

Context

The repo already has OpenSpec scaffolding (openspec/, .agent/workflows/openspec-*.md, two in-flight proposals) and Spec Kitty (.kittify/, one pilot mission for the org-gated signup work). What's missing is any archived spec under openspec/specs/ — nothing has ever been folded into the canonical spec set yet.

While reading the codebase end-to-end, nine runtime invariants stand out as load-bearing but unspecified anywhere reviewable:

1. Sysbox-runc runtime (no --privileged, AppArmor/seccomp unconfined)
2. coder user UID 1000 + docker GID 988 (parametric via var.docker_gid)
3. NOPASSWD sudo posture
4. In-container dockerd started by the agent script (host socket never mounted)
5. Two-volume persistence model (host bind for /home/coder, named volume for /var/lib/docker)
6. Copy-if-missing hydration from /home/coder-files/ (because the bind mount shadows image content)
7. Direct-bind single-project web routing (ddev-router globally omitted)
8. Host-aware cleanup via null_resource.workspace_cleanup + /usr/local/bin/coder-delete-workspace-dir
9. Env-sourced workspace identity (no hostname parsing)

Today these live across image/Dockerfile, user-defined-web/template.tf (+ its inlined startup_script), and prose in CLAUDE.md. A reviewer can't confirm a PR preserves them without re-reading three loosely coupled files.

Proposal

One descriptive-first OpenSpec change, add-workspace-runtime-contract, codifying the nine invariants as a single capability with ## ADDED Requirements, plus the required boot sequence and an explicit forbidden-behavior set (F-1 … F-10). The spec describes what is true today — no runtime behavior changes.

Six observed drift items are catalogued in a ## Known Drift block (informational, not enforced):

• image/scripts/.ddev/global_config.yaml referenced in CLAUDE.md but missing
• .ddev/commands/host/{launch,coder-routes,coder-setup} staged but never copied
• coder-setup missing chmod 755
• Dual dockerd-start models (systemd unit + manual sudo dockerd)
• chmod 666 /var/run/docker.sock broader than necessary
• Single-tag image version (VERSION) across all four templates

Each drift item becomes its own follow-up OpenSpec change after this lands.

Non-Goals

• No code changes. Nothing under image/, */template.tf, */scripts/, or Makefile is touched.
• No CI gates added (reserved for a future proposal).
• No drift remediation in this PR.
• No CLAUDE.md reconciliation (follows after archive).
• No freeform template coverage (separate sibling capability later).

Draft PR

#149 (draft, ~218-line spec + supporting proposal/design/tasks + Spec Kitty mission artifacts).

openspec validate add-workspace-runtime-contract --strict is green.

The question for the maintainers

Do you want this style of governance in the repo at all?

Open to redirection on scope, format, or whether to do this at all.

[rfay]

Not entirely sure what this means,

load-bearing but unspecified anywhere reviewable

I assume that's AI-talk?

[jonesrussell]

Not entirely sure what this means,

load-bearing but unspecified anywhere reviewable

I assume that's AI-talk?

It added that one paragraph out of nowhere. The issue should be draft too, really. I'm still triple checking things and reading up more on OpenSpec.

[rfay]

Another interesting note, Github apparently (just?) open-sourced https://github.com/github/spec-kit which seems to be a direct competitor.

[jonesrussell]

Another interesting note, Github apparently (just?) open-sourced https://github.com/github/spec-kit which seems to be a direct competitor.

Ah! I have to look but I thought that was what spec kitty was forked from. Must be a different one.

[jonesrussell]

This is the only artifact in the PR of note is https://github.com/jonesrussell/coder-ddev/blob/11096972fdddd29470229b2c898306aeb9442fc3/openspec/changes/add-workspace-runtime-contract/specs/workspace-runtime/spec.md