refactor(open-core): skip private submodules in recursive init, public ENTERPRISE.md, edition in /api/version (#1443)

[vybe]

Summary

• Frictionless OSS clone: both private submodules (.claude, src/backend/enterprise) now carry update = none in .gitmodules — a fresh public clone + git submodule update --init --recursive (and git clone --recurse-submodules) completes without credentials; git skips them with exit 0. Verified end-to-end in clean-room clones.
• Public seam doc: new docs/ENTERPRISE.md documents the generic open-core mechanism only (mount, HTTPS-PAT override, rebuild, verify) — passes the enterprise-docs-guard grep (run locally).
• Edition surface: GET /api/version now returns edition: "oss" | "enterprise" plus enterprise_features, both derived from entitlement_service.list_entitled_features() — the same source as feature-flags, so the two surfaces can't diverge. Reflects live registration state, not submodule-on-disk. Drive-by: the hardcoded runtimes list was stale (missing codex, Codex harness MVP — pluggable agentic execution engine alongside Claude Code #1187).
• Deploy pipeline hardened: under update = none a skipped submodule exits 0, so deploy-dev.yml's old exit-code success check would have silently degraded the dev deploy to OSS-only with a green log. It now persists the durable update = checkout local override before init and judges success by the populated marker file.
• Contributor docs: CLAUDE.md .claude setup rewritten to the verified config-first flow (a one-shot --init --checkout copies none into local config, so later plain updates silently skip again — the config line must come first), plus an external-contributor path via the public abilities dev-methodology plugin. README gains a one-line pointer.

⚠️ For entitled operators (existing clones)

Existing clones have no protective local update key for the enterprise submodule (unlike .claude, whose update = checkout was copied at init). After this lands, plain git submodule update starts skipping it — run once:

git config submodule.src/backend/enterprise.update checkout

(Documented in docs/ENTERPRISE.md; trinity-ops-public runbooks should pick this up too.)

Changes

• .gitmodules, .github/workflows/deploy-dev.yml, .github/workflows/build-without-submodule.yml
• src/backend/main.py (_build_version_payload + get_version — builder stays stdlib-pure for the exec-slice test harness; handler imports entitlement_service function-locally so _set_for_testing stubs work)
• docs/ENTERPRISE.md (new), README.md, CLAUDE.md
• docs/memory/requirements/infrastructure.md (§35.2), docs/memory/architecture.md, docs/memory/learnings.md
• tests/unit/test_926_version_endpoint.py (+3 tests, call sites updated), tests/registry.json

Test Plan

• pytest tests/unit/test_926_version_endpoint.py — 8/8 pass (passthrough, runtimes, static function-local-import guard)
• Clean-room clone + new .gitmodules: --init --recursive skips both submodules, exit 0, no credential prompt (GIT_TERMINAL_PROMPT=0, SSH BatchMode)
• Opt-in path: after git config submodule.src/backend/enterprise.update checkout, plain --init genuinely attempts the clone
• enterprise-docs-guard grep run locally over docs/ + CLAUDE.md — clean
• CI: build-without-submodule.yml now also asserts /api/version → edition: "oss" (end-to-end handler wiring)
• Note: test_847_entitlement_seam.py::test_submodule_registers_audit_not_sso fails locally on submodule-mounted clones — pre-existing staleness vs the SSO-OIDC merge (feat(sso): OSS gated surface for enterprise SSO (OIDC) (#32) #1303), skips in CI; filed test: test_submodule_registers_audit_not_sso is stale since SSO-OIDC landed (#1303) — fails locally whenever the enterprise submodule is mounted #1447.

Fixes #1443

🤖 Generated with Claude Code

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[vybe]

/review (adversarial, second pass) — 2 findings fixed in 55fb35b6, 3 more resolved as docs/comment corrections; no criticals remain.

All git mechanics were re-verified empirically by an independent reviewer (10 throwaway-repo experiments — config-key syntax, init-copy semantics, pre-existing-clone asymmetry, --remote skip, clone --recurse-submodules, recurse×none interaction): every documented command works as written.

Fixed on the branch:

• F1 (high): ENTERPRISE.md step 3 said "rebuild the backend" — factually wrong (the image's COPY allowlist excludes enterprise/; the code arrives via bind-mount only). Rewritten with the dev-restart vs prod-overlay split. Following the old text on a prod stack dead-ended at "submodule not present".
• F2 (medium): deploy-dev.yml could print a green initialized at <sha> for a stale tree (marker file survives a failed update on a previously-mounted VM). Now warns on checked-out-SHA vs recorded-gitlink drift.
• F3 (medium): docker-compose.prod.enterprise.yml comments documented update procedures (--init --recursive, --remote) that silently no-op under update = none; now require the one-time local override.
• F4/F5 (low): docs wording corrected (ANY init path copies none into local config, not just --init --checkout); passthrough test now pins the property with a mismatched edition/features pair.

Follow-ups filed: trinity-enterprise#88 (private ENTERPRISE_LOCAL_DEV.md documents the same now-skipping commands), #1450-class comment-disclosure issue (main.py seam comment; pre-existing, out of scope here), #1447 (pre-existing stale test, unrelated).

[dolho]

Review — LGTM ✅ (minor nits, none blocking)

Read the full diff + verified against the tree. Clean, well-tested, all 18 CI checks green (incl. backend boots without enterprise submodule asserting edition=oss end-to-end). The three empirically-verified git behaviors in learnings.md (skip exits 0, --init copies the strategy local, asymmetric protection of existing clones) are exactly the traps a naive rollout hits — good that each is handled in code, not just documented.

Verified during review:

• _build_version_payload has a single caller (the handler) — both sides updated, no stale callsite. ✅
• entitlement_service.list_entitled_features() exists; edition derives from its non-emptiness → provably can't diverge from enterprise_features. ✅
• Function-local import matches the routers/settings.py pattern and is pinned by the new static guard test. ✅
• Runtimes ["claude-code","gemini-cli","codex"] match KNOWN_RUNTIMES in runtime_adapter.py exactly. ✅
• No CI workflow depends on .claude auto-init, so flipping it to update = none is safe. ✅

Nits (follow-up, not blocking):

1. runtimes list is still hardcoded — this PR's drive-by fixes a staleness (codex missing) that recurs by construction; the next runtime will re-stale it. I get why it isn't derived from KNOWN_RUNTIMES (that lives in the agent-server tree and the builder is deliberately stdlib-pure for the exec-slice harness). Suggest a one-line comment next to the literal pointing at runtime_adapter.KNOWN_RUNTIMES as the source of truth, so the next person greps their way to updating both.

2. F2 drift warning is the right instinct — comparing the recorded gitlink SHA vs the checked-out SHA catches "populated but stale after a failed update." It only ::warning::s (non-fatal), which is consistent with enterprise-being-optional, but it does mean a stale enterprise tree can still ship under a green deploy. That's an acceptable tradeoff given the policy; just flagging that the warning is the only signal — worth making sure someone actually watches deploy-dev warnings.

3. Existing-operator migration (the git config submodule.src/backend/enterprise.update checkout one-liner) is handled well and documented in three places. Confirm trinity-ops-public runbooks get the same note, as the PR body suggests — that's the one surface outside this repo that silently changes behavior.

Nice work on the docs — ENTERPRISE.md is thorough, guard-compliant, and the HTTPS-PAT path avoids ever committing a token. Approving from my side once the runtimes comment (nit 1) is added or explicitly waved off.