tking/gsh
SHA256
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gsh/CLAUDE.md
Tyler J King 061e2206ea docs: add CLAUDE.md 
Documents the 2 crates (gsh binary + libgsh library), the GSH_*
env-var contract that bascule sets and forge-fuse reads (Phase 3
shell-IS-session), the cross-workspace dependency on
forge-core::CorpusCapabilityCeiling for the runtime three-way
intersection, and the local dev-environment/ playbook for the
WSL2 + Bascule + Hetzner Keycloak + Entra federation flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Tyler J King <tking@guildhouse.dev>
2026-05-04 11:41:30 -04:00

2.1 KiB
Raw Permalink Blame History

CLAUDE.md — gsh

The governed shell. Operator-facing CLI that bascule launches after OIDC → DID derivation; the binary that consumes GSH_* env vars, loads the AC, validates the corpus, and runs governed commands. Substrate-level (carries the Guildhouse brand intentionally per TODO.md Layout Principle).

Crates

  • gsh — The governed shell binary itself (GCAP-SPEC-SHELLBOUND- SDK-0001). Consumes GSH_DID, GSH_ACCORD_HASH, GSH_SHELL_CLASS, GSH_POSTURE_LEVEL, GSH_CAPABILITY_SET from bascule + propagates to subprocesses via org-ops-core::context::GshContext headers.
  • libgsh — Library: AC validation, capability-request building, corpus gate. The shell binary's reusable surface.

Cross-workspace dependencies

Consumes: guildhouse-did (Did parsing/derivation), bascule-workspace/bascule-core (AuthorizationContext shape), org-ops-core (env-var contract for child-process governance threading), forge-core::shell_context (re-exported CorpusCapabilityCeiling for runtime intersection).

Consumed by: the operator's interactive session — invoked by bascule-shell after OIDC auth, by dev-environment/bascule-local.toml locally on WSL2.

Build / Test

CARGO_TARGET_DIR=target-tking cargo build --workspace
CARGO_TARGET_DIR=target-tking cargo test  --workspace

Architectural notes

  • GSH_* env contract is the load-bearing interop with bascule (which sets them) and forge-fuse (which reads them via forge-fuse::ShellContext::from_env). The contract: GSH_DID, GSH_ACCORD_HASH, GSH_SHELL_CLASS=Application|System, GSH_POSTURE_LEVEL (1..=5 DEFCON), GSH_CAPABILITY_SET (hex bitmask 0x{:08x}).
  • Phase 3 forge-fuse (shell-IS-session) consumes these env vars to compute the per-mount effective capability via manifest_cap ∩ shell_cap ∩ corpus_cap.
  • Local dev environment at dev-environment/ shows the WSL2 + Bascule + gsh + Hetzner Keycloak + Entra federation flow end-to-end.
  • The brand-bound gsh name (vs a substrate-shell) is preserved intentionally — revisit when the substrate brand solidifies.