Environment-awareness tooling: allod env + capability descriptor contract #99

New issue

Open

opened 2026-07-11 12:49:59 +01:00 by allod-agent · 0 comments

allod-agent commented

2026-07-11 12:49:59 +01:00

Member

User story: So that I can tell at session start what an environment is allowed to read or push, public tooling needs a shared capability descriptor and commands that surface those permissions clearly.

Part of the "Environment identity & capability descriptor" arc.

Problem

A session's capabilities — which repos it can read, whether it can push to
public — are implicit in Forgejo ACLs and only surface when an operation hits a
wall. Neither the human nor the agent can tell, at session start, which
environment they are in (allod-dev is blind to private repos; nix-dev cannot
push public). This is the public, framework-agnostic half of a cross-repo effort
to make environment identity ambient; the private half (rendering the descriptor
from inventory and wiring the UX surfaces) is tracked separately in the private
stack.

Scope (allod/tools)

Public tooling that reads a descriptor the private side produces:

Descriptor contract. Define and document /etc/allod/env.json (plus a
human-readable /etc/allod/env.txt), schema
{ hostname, forge_identity, can_read_private, can_push_public, reachable_repos, summary },
so the private provisioner has a fixed target.
allod env (alias allod whoami): print the environment
human-readably, color-coded by capability; --json for machine use; degrade
gracefully by deriving from hostname + forge identity (and saying so) when the
descriptor is absent.
Env-aware pre-push guard in git-hooks/ (same pattern as
protected-refs-policy): block a push the current environment is not allowed
to make, failing early with a message that names the environment and the relay
path instead of an opaque Forgejo auth error.
Session-start reporter: emit the one-line environment summary for an
agent SessionStart hook / status line to consume (the wiring itself is
private-side).

All four read the same descriptor — one brain, many faces.

Out of scope

Producing the descriptor (private nexus/inventory); status line, shell
prompt, and MOTD wiring (private profiles).

Done when

allod env reports correctly on a descriptor-provisioned VM and degrades without
one; the guard blocks a disallowed push in a fixture with a clear,
environment-named error; tests cover both paths. Environment-awareness also folds
naturally into the forge/allod Go rewrite (#98).

**User story:** So that I can tell at session start what an environment is allowed to read or push, public tooling needs a shared capability descriptor and commands that surface those permissions clearly. _Part of the "Environment identity & capability descriptor" arc._ --- ## Problem A session's capabilities — which repos it can read, whether it can push to public — are implicit in Forgejo ACLs and only surface when an operation hits a wall. Neither the human nor the agent can tell, at session start, which environment they are in (`allod-dev` is blind to private repos; `nix-dev` cannot push public). This is the public, framework-agnostic half of a cross-repo effort to make environment identity ambient; the private half (rendering the descriptor from inventory and wiring the UX surfaces) is tracked separately in the private stack. ## Scope (allod/tools) Public tooling that reads a descriptor the private side produces: - [ ] **Descriptor contract.** Define and document `/etc/allod/env.json` (plus a human-readable `/etc/allod/env.txt`), schema `{ hostname, forge_identity, can_read_private, can_push_public, reachable_repos, summary }`, so the private provisioner has a fixed target. - [ ] **`allod env`** (alias `allod whoami`): print the environment human-readably, color-coded by capability; `--json` for machine use; degrade gracefully by deriving from hostname + forge identity (and saying so) when the descriptor is absent. - [ ] **Env-aware pre-push guard** in `git-hooks/` (same pattern as `protected-refs-policy`): block a push the current environment is not allowed to make, failing early with a message that names the environment and the relay path instead of an opaque Forgejo auth error. - [ ] **Session-start reporter**: emit the one-line environment summary for an agent SessionStart hook / status line to consume (the wiring itself is private-side). All four read the same descriptor — one brain, many faces. ## Out of scope Producing the descriptor (private `nexus`/`inventory`); status line, shell prompt, and MOTD wiring (private `profiles`). ## Done when `allod env` reports correctly on a descriptor-provisioned VM and degrades without one; the guard blocks a disallowed push in a fixture with a clear, environment-named error; tests cover both paths. Environment-awareness also folds naturally into the `forge`/`allod` Go rewrite (#98).