RFC #289: land phase-1 host integration contract

[loocor]

Context

• builds the phase-1 implementation checkpoint for RFC RFC: define a standard host integration contract for gstack #289 (RFC: define a standard host integration contract for gstack)
• focuses on the install/runtime boundary first so future OpenCode or adjacent host work can build on a shared contract instead of more one-off branches
• keeps the roadmap intentionally incremental: land the contract foundation now, normalize more host semantics next, then use a second host to validate the model

What This PR Lands

• introduce scripts/host-registry.ts as the single source of truth for host layouts, discovery roots, runtime roots, path rewrites, and generated output locations
• make ~/.gstack the canonical shared runtime home, with host-specific roots becoming thin discoverability layers and repo-local .gstack acting as the workspace sidecar/fallback
• rewire setup, scripts/gen-skill-docs.ts, scripts/skill-check.ts, packaging, and regression tests to the shared contract
• separate generated discoverability artifacts from runtime assets and regenerate the affected Claude/Codex/agents skill docs, including the new CODEX_PLAN_REVIEW placeholder support merged from upstream
• fold in the install/runtime hardening that fell out of dogfooding this contract: workspace discovery cleanup, shared-vs-workspace resolution checks, upgrade-path tightening, and a small browse loopback fix for chunked responses

Why The Diff Is Large

• most of the volume is generated SKILL.md output and contract-driven rewrites flowing from the registry / shared-runtime change
• the behavioral core is concentrated in scripts/host-registry.ts, scripts/gen-skill-docs.ts, setup, scripts/skill-check.ts, browse/src/cli.ts, and the related tests

Roadmap Progress

• Phase 1 — install/runtime contract: landed in this PR
• Phase 2 — host-specific skill semantics: still next; interactive prompting, invocation primitives, and metadata/frontmatter policy should keep moving onto the same host contract instead of remaining template-level special cases
• Phase 3 — second-host validation: intentionally deferred until the phase-2 surface is clearer; OpenCode remains the most useful candidate to prove the contract rather than arriving as a one-off exception

Intentionally Not In Scope

• no full OpenCode adapter yet
• no attempt to solve every host/runtime capability difference in one pass
• no broad host expansion beyond the install/runtime contract needed to make future host work coherent

Test Plan

• bun test test/gen-skill-docs.test.ts
• bun run skill:check
• git diff --check

Refs #289

🤖 Generated with Claude Code

[loocor]

Reviewer guide — if you want the shortest path through this PR, I’d focus on these in order:

1. scripts/host-registry.ts

   • This is the contract proposal in code: host layouts, discovery roots, runtime roots, path rewrites, and generated output locations.
   • Main review question: does this surface capture the real host/runtime boundary cleanly enough for future hosts, or is anything important still missing?

2. setup

   • This is where the contract becomes install semantics.
   • Main review question: is the ~/.gstack canonical runtime + thin host-root / workspace-sidecar model the right split?

3. scripts/gen-skill-docs.ts + generated SKILL.md output

   • This shows whether template generation is now following the contract instead of ad hoc path rewrites.
   • Main review question: are discoverability artifacts and runtime assets now separated in the right way?

4. scripts/skill-check.ts + test/gen-skill-docs.test.ts

   • These are the guardrails proving the contract is testable rather than just documented.
   • Main review question: do these tests/checks lock the important invariants, or are any contract edges still untested?

5. browse/src/cli.ts

   • This is just a small opportunistic fix picked up while validating the runtime path: chunked loopback HTTP responses now decode correctly.
   • Safe to review separately from the main host/runtime design.

The biggest thing I’d love feedback on is whether this PR now makes the host/runtime boundary explicit enough that a second host can plug into it later without us falling back into more one-off install/discovery exceptions.