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

[jonesrussell]

Tracking: #150

Summary

Establishes workspace-runtime-contract as the foundational Spec Kitty / OpenSpec specification for coder-ddev. Descriptive-first: codifies the nine runtime invariants already enforced today by image/Dockerfile, user-defined-web/template.tf, and the inlined startup_script. No image, template, script, or Makefile changes.

• OpenSpec change-id: add-workspace-runtime-contract
• Spec Kitty mission: workspace-runtime-contract-01KRC8WY

This PR is a draft — please review the spec text before marking ready.

What's in this PR

Surface	Contents
openspec/changes/add-workspace-runtime-contract/	Proposal, design, tasks, and the new delta spec at specs/workspace-runtime/spec.md
kitty-specs/workspace-runtime-contract-01KRC8WY/	Spec Kitty mission artifacts (spec, plan, research, data-model, WPs, status)

The delta spec adds nine ADDED Requirements covering:

1. Sysbox container runtime (no --privileged)
2. Workspace user identity (coder, UID 1000, parametric docker GID)
3. NOPASSWD sudo posture
4. In-container dockerd lifecycle (agent-started, no host socket mount)
5. Two-volume persistence model (host bind + named volume)
6. Copy-if-missing home hydration from /home/coder-files
7. Direct-bind single-project web routing (no ddev-router globally)
8. Host-aware cleanup via null_resource.workspace_cleanup
9. Env-sourced workspace identity (no hostname parsing)

Plus the required agent boot sequence and a forbidden-behavior set (F-1 … F-10) capturing what the contract explicitly disallows.

Known Drift (informational, not remediated here)

The spec carries a ## Known Drift block enumerating six anomalies (global_config.yaml missing, uncopied DDEV host commands, missing chmod 755 on coder-setup, dual dockerd-start models, broad socket chmod, single-tag image version). Each will become its own follow-up OpenSpec change attached to the relevant invariant.

Why descriptive-first

This is the first spec in openspec/specs/ (none have been archived before). Trying to prescribe behavior before capturing current behavior would create gratuitous drift. By describing what already works, every future change has a stable, verifiable anchor.

Non-Goals

• No edits to image/, */template.tf, */scripts/, or Makefile.
• No CI gate added — reserved for a future proposal.
• No remediation of drift D-1 … D-6.
• No CLAUDE.md reconciliation (follows in a separate change after archive).
• No freeform template coverage (separate sibling capability later).

Validation

• ✅ openspec validate add-workspace-runtime-contract --strict — green
• ✅ Diff scope confined to kitty-specs/workspace-runtime-contract-01KRC8WY/ and openspec/changes/add-workspace-runtime-contract/
• ➖ terraform fmt -recursive — N/A (no HCL touched; defensive run not performed because terraform was unavailable in the dev environment)

Test plan

• Review the nine ## ADDED Requirements for accuracy against current image/Dockerfile + user-defined-web/template.tf + inlined startup_script
• Confirm each requirement has at least one #### Scenario:
• Verify the forbidden-behavior set (F-1 … F-10) matches existing review heuristics
• Confirm ## Known Drift block accurately names the six anomalies and points at the right files
• Verify Spec Kitty ↔ OpenSpec cross-link in kitty-specs/.../meta.json (openspec_change_id) and in openspec/changes/add-workspace-runtime-contract/proposal.md ("Spec Kitty Mission")
• openspec validate add-workspace-runtime-contract --strict re-run locally
• terraform fmt -check -recursive re-run locally (expected: zero changes)

Follow-ups (not in scope here)

1. remediate-ddev-global-config — fix drift D-1.
2. install-ddev-host-commands — fix drift D-2.
3. chmod-ddev-host-commands — fix drift D-3.
4. retire-systemd-dockerd — fix drift D-4 (remove the dormant systemd path).
5. tighten-docker-socket-mode — fix drift D-5.
6. claude-md-reconciliation — retire architecture prose now superseded by this spec.

🤖 Generated with Claude Code

[rfay]

Thanks for paying attention! Not entirely sure what much of this means.