shared graphs: the gate on the server, and knoten serve for remotes friends can be invited to

[BY571]

A graph is a folder in git, so sharing one is already git push. What was missing is the
gate. knoten hook protects the person who ran it, in the clone they ran it in, and
git commit --no-verify walks past it. On a shared graph the normal contributor is one
who never ran it, which left the rules resting on everyone's individual discipline. That
is precisely the failure the rule engine exists to replace.

What this adds

knoten hook --server [REPO] installs a pre-receive hook on the repo everyone pushes
to. It unpacks the tree being pushed, finds every graph in it, runs knoten validate
on each, and refuses the push if any fails.

# on any box you and your collaborators can reach
git init --bare lab-graph.git
knoten hook --server lab-graph.git

# everyone else, human or agent
git clone you@box:lab-graph.git

No CI, no runner, no minutes, and nobody can skip it from a laptop. It is also strictly
better than a CI check for this job: it refuses the push instead of reporting afterwards
that master is broken.

Three things it has to get right

Each has a test that fails without it.

It finds the graph rather than recording a path. A bare repo has no working tree, so
there is no graph.yaml to read at install time. A path recorded then would rot the
moment someone moved the folder, and rot silently: the hook would find no graph and
accept everything while reporting green.

It fails closed. knoten missing from the server's PATH refuses the push rather than
waving it through. The test actually strips PATH rather than grepping the script for a
guard.

graph.yaml is not a name knoten owns. Another tool's config of the same name fails
validation, and treating it as a graph would make the whole repo unpushable forever,
citing a file nobody thinks of as a graph. A graph is one with a nodes/ directory or
a knoten-specific key. Both tests are needed: git does not track an empty nodes/, so a
graph whose nodes were all deleted slips through the first, and a graph.yaml too
malformed to name its keys slips through the second.

One shell detail worth flagging in review: git archive and tar are two statements
rather than a pipe, because POSIX sh reports only the last command's status. A pipeline
would hide a failed archive behind a happy tar and accept the push unchecked.

Testing

tests/test_server_hook.py, 23 tests, all doing real pushes against real bare repos
rather than asserting on the script's text. Full suite 314 passed.

Covered: rejection and acceptance; a graph in a subdirectory; two graphs in one repo;
a repo with no graph; branch deletion (all-zeros sha); knoten absent from PATH; an
unrelated graph.yaml; malformed graph.yaml; an unparseable node; deleting the graph;
every ref in one git push --all; a non-master branch; a force push; a tag; temp
directory cleanup under a controlled TMPDIR; and a repo path containing a space, which
is the classic way this breaks and it breaks open.

Verified end to end outside the suite: a contributor who never ran knoten hook and used
git commit --no-verify was still refused, and the server kept only the clean commit.
knoten viz was rendered from a fresh clone of the shared repo to confirm the read-only
path needs nothing installed.

Docs

README gains a ## A shared graph section covering the setup, why nodes go straight to
master while graph.yaml is the file worth protecting, why concurrent edits do not
collide (edges are declared once on the subject, back-links are generated at load), and a
pointer to Forgejo for anyone wanting per-user permissions or required approvals, since
that is the forge's job and not knoten's. SKILL.md gains a pull-first line, because a
frontier computed from a week-old clone recommends work a collaborator already settled.

Not in scope

Cross-graph citation, a graph-level diff, and any notion of accounts or approval quorums.
Approval quorums in particular belong in a forge: pre-receive is binary and has no
pending state, so building "this needs two approvals" on bare git means reinventing pull
requests.

🤖 Generated with Claude Code

https://claude.ai/code/session_013cJ97A5dq8ww3d7qoDfYxb