423e2c35

Governance: unlisted by default, published by explicit rule

a73x 2026-08-11 16:45

Commit message

Governance: unlisted by default, published by explicit rule

The spec said to delete server.toml and drop --config. Both are wrong,
and for the same reason: access.conf grants to named principals and
@all means every enrolled key, so nothing in the language could
describe an unauthenticated request. Deleting server.toml deleted the
anonymous axis with nothing left to express it.

Invert the default instead. A repository is unlisted and unreadable
without authentication unless a rule says otherwise, so absence of
config is a decision and settings.git only expresses the exception.
@anonymous becomes a reserved principal in the rule table (an access
decision, first-match-wins like any other, never satisfying a write);
listed becomes an option (a display decision), stolen from gitolite
rather than invented.

--config stays, reduced to bootstrap: repos_dir and the listeners must
be read before settings.git can be found, since it lives under
repos_dir.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-08-09-repo-governance-design.md

+`tools.git` and `tools` already collide there. HTTP resolution and the URL scheme
+must be reworked as part of this.
+## Exposure: unlisted by default, published by rule
+Revised 2026-08-11. The original text below assumed `server.toml` could simply
+be deleted; it cannot, and the reason is worth stating because it is the same
+reason the rule language needs a new token.
+`access.conf` grants to **named principals**, and `@all` means every *enrolled*
+key — every identity with a file in `keydir/`. That is a strictly different set
+from "anybody at all", so no rule in the language as specified can describe an
+unauthenticated HTTP request. Deleting `server.toml` would therefore delete the
+anonymous axis with nothing left to express it, which is why the implementation
+(`b6dcbb7b`) kept `visibility`, `[ui] anonymous` and `[http] anonymous_clone`
+there and had `settings.git` supersede it only on the access axis.
+The fix is to invert the default rather than to translate the old keys.
+**A repository is unlisted and unreadable without authentication unless a rule
+says otherwise.** The absence of configuration is then a decision rather than a
+gap, and `settings.git` only ever has to express the *exception* — a positive
+grant, which is what the language is already good at. This also generalises a
+special case the implementation already had to hand-code: `settings.git` is
+forced off the anonymous surface unless it opts in, because creating it must not
+publish the key roster to an internet-facing UI.
+Two axes, deliberately separate, because "not in the list" and "404 to a direct
+URL" are different states and a repo reachable if you know its name is a real
+configuration:
+```
+repo tools
+    RW+                   =   @admins
+    RW      refs/collab/  =   @agents
+    R                     =   @all          # every enrolled key
+    R                     =   @anonymous    # unauthenticated read: reachable by name
+    option listed         =   yes           # and advertised in the repo list
+```
+`@anonymous` is a **reserved principal** and belongs in the rule table because it
+is an access decision, resolved by the same first-match-wins evaluation as any
+other — including `-` to deny it back. `listed` is an **option**, not a rule,
+because advertising is a display concern rather than an access one; this is the
+`option` line gitolite already has, so it is stolen rather than invented.
+`listed` implies nothing about readability: a repo listed but not
+`R = @anonymous` appears only to viewers who can read it.
+`@anonymous` must never satisfy a write grant. `RW = @anonymous` is a config
+error and is rejected by push validation, not silently ignored.
+### Bootstrap, corrected
+The server reads its storage location and listener addresses before it can read
+any git object — including before it can find `settings.git`, which lives under
+`repos_dir`. Those cannot move into git without a chicken-and-egg problem, so
+`--config` **stays**, reduced to bootstrap only: `repos_dir`, `http_bind`,
+`ssh_bind`, and the host key location. Equivalent startup flags are a fine
+addition but not a replacement.
+Everything that is not needed to reach `settings.git` does move into it:
+`site_title`, `max_release_size`, and the exposure axes above. `authorized_keys`
+(`session.rs:417`, re-read on every auth attempt) is replaced by `keydir/`,
+which also removes the per-attempt file read.
+An init container creates `settings.git` with one key in `keydir/` and a minimal
+`conf/access.conf` granting that principal `RW+` on `settings`. From there every
+change is a push.
+### Superseded text
+The original section read: *"these become startup flags: `--repos-dir`,
+`--http-bind`, `--ssh-bind`. They are config-file fields today
+(`config.rs:7-18`); the existing `--config` flag and `server.toml` are removed.
+`site_title` and `max_release_size` move into `settings.git`."* The removal of
+`--config` is wrong for the reason above; the rest stands.
+An init container creates `settings.git` with one key in `keydir/` and a minimal
+`conf/access.conf` granting that principal `RW+` on `settings`. From there every