Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,23 +34,21 @@ the Claude org console. No secrets or Infisical values are involved.
- `plugins/setkernel/`: the plugin: `skills/` (`verify`, `review-blockers`, `ship-pr`, and
`request-review` with its POSIX-sh helper), `agents/` (`explorer`, `reviewer`), `hooks/` (POSIX
sh: the `SessionStart` context hook, `git-guard.sh`, the `PreToolUse` git guard, `d1-guard.sh`,
the always-on `PreToolUse` D1 guard, the opt-in `Stop` verify gate, and the opt-in `persona.sh`
`SessionStart` hook).
the always-on `PreToolUse` D1 guard, and the opt-in `Stop` verify gate).
- `.claude-plugin/marketplace.json`: the `setkernel` marketplace; lists the one plugin.
- `rules/org-rules.md`: the one source of the org rules (becomes `claudeMd` in managed settings).
- `managed/settings.base.json`: hand-edited part of the managed settings (`permissions.deny`,
marketplace, enabled plugin).
- `bin/generate`: builds the generated files below from those sources.
- `bin/dependabot-policy`: writes the version holds into a repo's `dependabot.yml`.
- `tests/run.sh`: tests for the generator, the session hook, the verify gate, the D1 guard, the
persona hook, the request-review helper and `bin/dependabot-policy`.
request-review helper and `bin/dependabot-policy`.

## Traps and don't-touch
- Generated, never edit by hand: `managed/settings.json` and `plugins/setkernel/policy/holds.md`.
Edit the source, run `bin/generate`, commit both.
- This repo is public: no secrets, personal data or personas, ever. `rules/` names no private repo
but hq: `tests/run.sh` fails on a `setkernel/<name>` outside its `allowed_repos` list (decision 0007).
`persona.sh` fetches persona text from private hq at session start; its tests use made-up text.
- Hooks and scripts stay POSIX sh: the agent VMs have no Node. `bin/generate` avoids
`$(cat <<HEREDOC)` because bash 3.2 (macOS `/bin/sh`) mis-parses it when the text holds an
apostrophe.
Expand Down
25 changes: 3 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ from `main`; every merge needs Raghav's code-owner approval.
| Path | What it is |
| --- | --- |
| `.claude-plugin/marketplace.json` | The `setkernel` marketplace. It lists one plugin. |
| `plugins/setkernel/` | The org plugin: skills `verify`, `review-blockers`, `ship-pr`, `request-review`; subagents `explorer`, `reviewer`; POSIX-shell hooks: `SessionStart` session context, the opt-in `SessionStart` persona hook, the git guard (`PreToolUse` on Bash, see below), a `PreToolUse` guard that denies remote D1 writes (always on: it has no env switch) and the opt-in `Stop` verify gate. `plugin.json` has no `version`, so every commit on `main` is a release. |
| `plugins/setkernel/` | The org plugin: skills `verify`, `review-blockers`, `ship-pr`, `request-review`; subagents `explorer`, `reviewer`; POSIX-shell hooks: `SessionStart` session context, the git guard (`PreToolUse` on Bash, see below), a `PreToolUse` guard that denies remote D1 writes (always on: it has no env switch) and the opt-in `Stop` verify gate. `plugin.json` has no `version`, so every commit on `main` is a release. |
| `rules/org-rules.md` | **The one source of the org rules.** Every session gets them as `claudeMd` in the managed settings; a repo's `AGENTS.md` header links to setkernel/hq's `docs/repo-standard.md`, not to this file. |
| `managed/settings.base.json` | Hand-edited part of the server-managed settings: the org `permissions.deny` list, the marketplace, the enabled plugin, org-only hooks (`allowManagedHooksOnly`), merging with the VMs' policy file (`managedSourcesBehavior: "merge"`), login, update and retention policy, and the Claude Code telemetry `env` (OTLP to sk-obs01, content redacted; setkernel/hq#90). |
| `managed/settings.json` | Generated. The draft JSON Raghav pastes into the Claude org console (server-managed settings). |
| `bin/generate` | The generator (POSIX sh + `jq`). |
| `policy/versions.json` | **The one source of the org version holds** (Node, TypeScript, PHPCS, …). |
| `plugins/setkernel/policy/holds.md` | Generated. The holds as text; the plugin's SessionStart hook prints it into every Claude session. |
| `bin/dependabot-policy` | Writes the holds into a repo's `.github/dependabot.yml` (`--check` for drift; `crosses` tells whether a version crosses a hold). Python 3, standard library only. |
| `tests/run.sh` | Tests for the generator, the session hook, the verify gate, the D1 guard, the persona hook, the request-review skill and `bin/dependabot-policy`. |
| `tests/run.sh` | Tests for the generator, the session hook, the verify gate, the D1 guard, the request-review skill and `bin/dependabot-policy`. |

In Claude Code the plugin's components are namespaced: `/setkernel:verify`, `setkernel:reviewer`.

Expand Down Expand Up @@ -63,8 +63,7 @@ git guard covers only the git commands a text rule can't pin down. The other hoo
guard can't be switched off by a repo or user hook, and a repo's own hooks don't run.
Side effects: it also blocks `/goal`, hooks in agent frontmatter and in a project's settings, and
narrows `statusLine` to the managed settings. This plugin's hooks still run; a hook from a
GitHub-sourced mod does not, nor does a user-scope hook such as the VMs' old persona hook (its
replacement is the plugin's opt-in persona hook, below).
GitHub-sourced mod does not, nor does a user-scope hook.
- **Version pin**: `requiredMinimumVersion` 2.1.295 stops an older Claude Code from starting
(`minimumVersion` only limits updates). `autoUpdatesChannel` is `latest`, because `stable` still
resolved to 2.1.292, below the minimum. A seat below 2.1.295 has to update by hand once. The
Expand Down Expand Up @@ -172,24 +171,6 @@ canaried on one VM before it reaches every seat.
already passed is not checked again.
- State (baseline, last green tree, block count, last log) lives in `CLAUDE_PLUGIN_DATA`.

## The persona hook (SessionStart)

`hooks/persona.sh` loads a seat's persona into the session (setkernel/agent-plugins#37). It is a
port of setkernel/hq's `agents/vm/sk-persona.sh`, a user-scope hook that `allowManagedHooksOnly`
stops once the managed settings are pasted (setkernel/hq#332).
It is off unless `SETKERNEL_PERSONA=1` is set in the session's environment, so a machine that still
runs its own persona hook doesn't load it twice.

- It keys on the git email: only `<name>@setkernel.com`, with a name of lowercase letters, digits
and `-`. It fetches `agents/personas/<name>.md` from private setkernel/hq with the machine's own
`gh` login and prints it as `SessionStart` `additionalContext`. Needs `gh` and `jq`.
- **The persona text never enters this repo** (decision 0001): the hook, its tests and this README
hold none. It is cached owner-only (dir 700, file 600) in `CLAUDE_PLUGIN_DATA/persona`, else
`${XDG_CACHE_HOME:-~/.cache}/setkernel/persona`, and reused for `SETKERNEL_PERSONA_TTL` minutes
(360; 0 forces a fetch).
- Anything missing (no opt-in, another domain, no `gh` or `jq`, no access, no such persona, the
network down with no fresh cache) means no persona: it prints nothing and exits 0.

## Try the plugin locally

```sh
Expand Down
5 changes: 0 additions & 5 deletions plugins/setkernel/hooks/hooks.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,6 @@
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/verify-gate.sh\" start",
"timeout": 30
},
{
"type": "command",
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/persona.sh\"",
"timeout": 10
}
]
}
Expand Down
62 changes: 0 additions & 62 deletions plugins/setkernel/hooks/persona.sh

This file was deleted.

93 changes: 1 addition & 92 deletions tests/run.sh
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
#!/bin/sh
# Tests for bin/generate, the session hook, the verify gate, the D1 guard, the persona hook, the request-review skill and bin/dependabot-policy. POSIX sh; needs jq for the generator tests.
# Tests for bin/generate, the session hook, the verify gate, the D1 guard, the request-review skill and bin/dependabot-policy. POSIX sh; needs jq for the generator tests.
# Usage: tests/run.sh (set SHELL_UNDER_TEST=dash or "busybox sh" to try other shells)
set -eu

Expand Down Expand Up @@ -835,97 +835,6 @@ expect 0 '^$' "outside a git repo the gate lets the run stop" -- \
sh -c "printf '%s' '{\"session_id\":\"s4\"}' | env CLAUDE_PROJECT_DIR='$tmp/nogit' CLAUDE_PLUGIN_DATA='$gstate' SETKERNEL_VERIFY_GATE=1 $sh_cmd '$gate' stop"
expect 0 "" "the repo's own index is untouched" -- git -C "$gaterepo" diff --cached --quiet

# The persona hook (#37): opt-in, keyed on a setkernel email, fetched with a stub gh, owner-only cache.
# Made-up persona text only: real personas are private (decision 0001).
persona=$hooks/persona.sh
phome=$tmp/persona-home
pstub=$tmp/persona-stub
pdata=$tmp/persona-data
mkdir -p "$phome" "$pstub"
cat >"$pstub/gh" <<EOF
#!/bin/sh
echo "\$*" >>"$tmp/gh-calls"
[ -f "$tmp/gh-down" ] && { echo 'gh: error connecting to api.github.com' >&2; exit 1; }
case "\$*" in
*"repos/setkernel/hq/contents/agents/personas/zz-test.md"*) printf '# Made-up test persona\nLikes "quotes" and back\\\\slashes.\n' ;;
*) echo 'gh: Not Found (HTTP 404)' >&2; exit 1 ;;
esac
EOF
chmod +x "$pstub/gh"
# with_email <email>: the global git email the hook keys on.
with_email() { printf '[user]\n\temail = %s\n' "$1" >"$phome/.gitconfig"; }
# persona_hook [VAR=value…]: run the hook as Claude Code would, outside any repo, opted in.
# shellcheck disable=SC2120 # expect and silent pass the arguments
persona_hook() {
# shellcheck disable=SC2086 # sh_cmd may be "busybox sh"
(cd "$tmp" && printf '{"session_id":"p1"}' | env HOME="$phome" XDG_CACHE_HOME= GIT_CONFIG_GLOBAL="$phome/.gitconfig" \
GIT_CONFIG_NOSYSTEM=1 CLAUDE_PLUGIN_DATA="$pdata" PATH="$pstub:$PATH" SETKERNEL_PERSONA=1 "$@" $sh_cmd "$persona")
}
# silent <command…>: "silent" when the command exits 0 and prints nothing, stderr included.
silent() {
out=$("$@" 2>&1) && [ -z "$out" ] && echo silent
}
gh_calls() { if [ -f "$tmp/gh-calls" ]; then wc -l <"$tmp/gh-calls" | tr -d ' '; else echo 0; fi; }

expect 0 '^10$' "hooks.json runs the persona hook on SessionStart with a 10 s timeout" -- \
jq -r '.hooks.SessionStart[].hooks[] | select(.command | contains("hooks/persona.sh")) | .timeout' "$hooks/hooks.json"
with_email zz-test@setkernel.com
expect 0 "^silent$" "off unless SETKERNEL_PERSONA=1" -- silent persona_hook SETKERNEL_PERSONA=
expect 0 "^0$" "and gh is not called" -- gh_calls
for e in zz-test@example.com zz-test@setkernel.com.evil.example zz-test@notsetkernel.com; do
with_email "$e"
expect 0 "^silent$" "no persona for another domain: $e" -- silent persona_hook
done
for e in ../zz-test@setkernel.com a/b@setkernel.com zz.test@setkernel.com -rf@setkernel.com @setkernel.com 'a b@setkernel.com'; do
with_email "$e"
expect 0 "^silent$" "no persona for an unsafe name: $e" -- silent persona_hook
done
expect 0 "^0$" "none of those called gh" -- gh_calls
rm -f "$phome/.gitconfig"
expect 0 "^silent$" "no persona without a git email" -- silent persona_hook

with_email zz-test@setkernel.com
persona_hook >"$tmp/persona-out" 2>&1 || true
expect 0 "^true$" "opted in: SessionStart JSON with the persona as additionalContext" -- \
jq -e '.hookSpecificOutput.hookEventName == "SessionStart" and (.hookSpecificOutput.additionalContext | test("^Your persona \\(from setkernel/hq agents/personas/zz-test.md, private"))' "$tmp/persona-out"
expect 0 'Likes "quotes" and back\\slashes.' "the persona text arrives intact" -- jq -er .hookSpecificOutput.additionalContext "$tmp/persona-out"
expect 0 "^1$" "gh was called once" -- gh_calls
expect 0 "^drwx------" "the cache dir is owner-only" -- ls -ld "$pdata/persona"
expect 0 "^-rw-------" "the cached persona is owner-only" -- ls -l "$pdata/persona/zz-test.md"
expect 0 "^# Made-up test persona" "the cache holds the persona" -- cat "$pdata/persona/zz-test.md"
touch "$tmp/gh-down"
expect 0 "Made-up test persona" "a fresh cache is used while gh is down" -- persona_hook
expect 0 "^1$" "so gh was not called again" -- gh_calls
with_email ZZ-Test@SetKernel.COM
expect 0 "Made-up test persona" "the email's case does not matter" -- persona_hook
with_email zz-test@setkernel.com
expect 0 "^silent$" "SETKERNEL_PERSONA_TTL=0 forces a fetch; with gh failing, no persona and exit 0" -- silent persona_hook SETKERNEL_PERSONA_TTL=0
expect 0 "^2$" "and gh was called despite the fresh cache" -- gh_calls
rm -rf "$pdata"
expect 0 "^silent$" "gh failing with no cache: no persona, exit 0, gh's error not shown" -- silent persona_hook
rm -f "$tmp/gh-down"
with_email zz-nobody@setkernel.com
expect 0 "^silent$" "no such persona (gh 404): no persona, exit 0" -- silent persona_hook
expect 1 "" "and nothing is cached for it" -- test -e "$pdata/persona/zz-nobody.md"
with_email zz-test@setkernel.com
persona_hook >/dev/null
calls=$(gh_calls)
chmod 755 "$pdata/persona"
touch "$tmp/gh-down"
expect 0 "Made-up test persona" "a cache dir left wider is still used" -- persona_hook
expect 0 "^$calls$" "so gh was not called for it" -- gh_calls
expect 0 "^drwx------" "and made owner-only again" -- ls -ld "$pdata/persona"
rm -f "$tmp/gh-down"
rm -rf "$pdata"
expect 0 "Made-up test persona" "without CLAUDE_PLUGIN_DATA the cache is under XDG_CACHE_HOME" -- persona_hook CLAUDE_PLUGIN_DATA= XDG_CACHE_HOME="$tmp/persona-xdg"
expect 0 "^-rw-------" "and owner-only there too" -- ls -l "$tmp/persona-xdg/setkernel/persona/zz-test.md"
# Without jq there is no safe way to build the JSON here: no persona, exit 0.
pnojq=$tmp/persona-nojq
mkdir -p "$pnojq"
for t in "${sh_cmd%% *}" git tr find cat mkdir chmod mv rm env; do ln -s "$(command -v "$t")" "$pnojq/$t"; done
ln -s "$pstub/gh" "$pnojq/gh"
expect 0 "^silent$" "without jq: no persona, exit 0" -- silent persona_hook PATH="$pnojq" SETKERNEL_PERSONA_TTL=0

# bin/dependabot-policy: writes the block, is idempotent, keeps the repo's own ignores, lifts cleanly.
dp() { python3 "$root/bin/dependabot-policy" "$@"; }
dbrepo() {
Expand Down
Loading