/genesis-bootstrap — Fresh-Repo First-Owner Genesis Bootstrap Runbook

The operational runbook for establishing the multi-operator trust root in a repo that has the substrate installed but is NOT yet enrolled — no operators.roster.json with a genesis owner, no folded genesis-anchor. This is the step that PRECEDES /enroll and /ecosystem-init's genesis step on a truly fresh BUILD/USE repo.

The gap this fills. The authoritative end-to-end runbook (guides/co-setup/11-genesis-ceremony.md) lives at loom only and is absent from BUILD/USE repos. The shipped commands (/whoami --enroll-genesis, /ecosystem-init, /enroll) and the sibling skills (41-onboard, 43-ecosystem-init, 44-enroll) reference that loom guide for the operational depth. This skill reconstructs that depth IN the repo, plus the five hard-won guard traps that block a naive first run.

Where bootstrap sits among the onboarding surfaces

Reference the sibling skills — do NOT re-run their procedures here:

Bootstrap is the ONE case where there is no roster to register into. Once the genesis owner is anchored, every TEAMMATE self-enrolls from their OWN machine via /enroll (never bootstrapped for them) and starts each session with /onboard.

Pre-flight — five gates, in this order (order is load-bearing)

1. Signing key FIRST. Configure commit-signing BEFORE any tracked-file write. Absent a key,

signing-mutation-guard.js puts the session in degraded read-only mode — every tracked-file mutation is blocked. The predicate is a working-tree-mutation check (a git status --porcelain before/after delta on tracked paths), NOT a tool-name allowlist, so no file-mutation path escapes it. Configure repo-local:

   git config --local gpg.format ssh
   git config --local user.signingkey "$HOME/.ssh/id_ed25519.pub"
   git config --local commit.gpgsign true

(COC_OPERATOR_KEY_PATH="" or COC_SIGNING_MUTATION_GUARD_FORCE_DEGRADED=1 force degraded — never set these during a ceremony.)

1. On a codify branch. integrity-guard.js permits writes to watched paths

(operators.roster.json, operators.roster.schema.json, coordination-log.jsonl, posture.json, violations.jsonl, observations.jsonl, team-memory/**, journal/**) ONLY on a branch matching ^codify/<display_id>-YYYY-MM-DD$ (the date-terminal predicate at .claude/hooks/integrity-guard.js; suffixed names like …-b are rejected). Cut it from main (branch protection rejects a direct roster push to main):

   git checkout -b "codify/<display_id>-$(date -u +%Y-%m-%d)" main

1. Ceremony steps run script-by-path, never `node -e` / `python -c`. See § The

script-by-path pattern below — this is the trap that most often blocks a first run.

1. gh CLI reachable + authenticated. The ceremony makes live gh api calls

(repos/{owner}/{repo}, commits/{root_commit}, and for org repos orgs/{org}/memberships/{login}); it is fail-CLOSED — any failed verification refuses to emit the anchor.

1. Verify the fold is clean before declaring "enrolled." A signed-and-appended anchor that

does not FOLD clean is not a trust root. See § Verify below.

The bootstrap sequence

1. Hand-author the bootstrap roster on the codify branch. The /whoami --register path

assumes an EXISTING roster; on a fresh repo the first roster is authored by hand. The genesis owner's entry MUST carry role: owner, the correct github_login (the verified external repo owner), and the signing key's {type, fingerprint, pubkey}. person_id is pid-<display_id>-<short-fingerprint> (first 8 chars of sha256 of the pubkey body), immutable, and is the roster MAP KEY — resolveIdentity matches by keys[].fingerprint, so the map key need only be consistent, not re-derived. Set roster.genesis: { provider, repo_owner, repo_owner_kind: "user"|"org", root_commit }.

1. Schema-validate the roster BEFORE committing — valid: false is a hard stop:

.claude/hooks/lib/roster-schema-validate.js::validate(roster) returns {valid, errors[]}.

1. Configure signing (pre-flight gate 1) if not already done.
2. Run the ceremony via .claude/hooks/lib/genesis-ceremony.js::runEnrollmentCeremony(opts)

(signature at genesis-ceremony.js). opts keys: { roster, repo: {owner, name}, signingKeyPath, signingKeyFingerprint, ghApi, transportAppend, keyType }. signingKeyPath is the PRIVATE key; ghApi is a subprocess wrapper around gh api; transportAppend is a sync append of the signed record to .claude/learning/coordination-log.jsonl. Returns { ok, error?, reason?, step? }, fail-CLOSED. (The same path /whoami --enroll-genesis drives — see commands/whoami.md.)

1. Verify (next section).

The genesis-anchor lands in .claude/learning/coordination-log.jsonl (gitignored, per-clone local state — NO commit, NO PR for the anchor itself). Appending it through a node <file> script does NOT trip genesis-anchor-guard.js (that guard fires on Bash git commit / git push and on edit-tool mutations of the roster, not on a plain node subprocess). The ceremony writes its OWN signed enrollment marker (COC_GENESIS_GUARD_ENROLLMENT_MARKER) that the guard verifies — an unsigned marker is not a bypass.

org-owned vs user-owned (the #358 relaxation)

The verified-identity ANCHOR differs by repo_owner_kind:

• user-owned — the SIGNED ROOT COMMIT is the anchor:

gh api repos/{owner}/{repo}/commits/{root_commit} → verification.verified == true AND the verified author == the declared owner.

• org-owned — many org repos have an UNVERIFIED root commit (authored by a contributor who

did not sign). The issue-#358 relaxation substitutes a verified active org-admin attestation: gh api orgs/{org}/memberships/{login} → role: "admin" + state: "active" for the signing person. This is the structurally-equivalent anchor to a signed root commit. It applies ONLY to org-owned repos AND only when the signer is a verified active admin; it does NOT apply to user-owned repos.

The ceremony also requires the external owner to match: gh api repos/{owner}/{repo} → owner.login == roster.genesis.repo_owner, and the roster to declare exactly ONE owner person whose github_login resolves to that login, bound to the signing key's fingerprint.

The script-by-path pattern (the central trap)

validate-bash-command.js runs detectStateFileMutation(command, STATE_PATH_RX) on every Bash command — a three-layer detector (its docstring at validate-bash-command.js: "redirects, file utilities, interpreter -c/-e/-m bodies") that BLOCKS (severity: block) any command whose body MUTATES a watched state file. STATE_PATH_RX matches posture.json, violations.jsonl, coordination-log.jsonl, .initialized, the heartbeat/session-end caches, and operators.roster.json. So a node -e '…fs.writeFileSync(".claude/operators.roster.json"…)' roster write is blocked — the state-file path is on the command line the detector scans. (This is why the illustrative node -e in commands/whoami.md § --register is blocked in practice; that command's "Implementation notes" name the "ceremony-script-by-path constraint.")

The fix is NOT to weaken the guard. Route every state-mutating ceremony step through a script:

# DO — author a script file, run it as a BARE `node <file>`.
#   The watched path lives in the script BODY, off the scanned command line.
#   (Write the script to a scratch path, then:)
node /path/to/ceremony-step.js

# DO NOT — inline interpreter body that writes a watched state file
node -e 'require("fs").writeFileSync(".claude/operators.roster.json", x)'   # BLOCKED

Keep node <file> a BARE command — bundling it with gh … or a heredoc in one compound command can re-introduce a scanned mutation token. Read-only node -e (no watched-state path) is NOT blocked; only state-file mutation is.

Verify (before declaring "enrolled")

1. Fold clean — .claude/hooks/lib/coordination-log.js::foldLog(records, roster, opts)

(public export) returns { foldState, accepted, rejected, forks, advisories, contestedRevocations, derivedN }. A healthy genesis: accepted includes the anchor, rejected: [], forks: []. Run it script-by-path (it reads the gitignored log).

1. Identity resolves to owner —

.claude/hooks/lib/operator-id.js::resolveIdentity(repoDir) returns { verified_id, person_id, display_id, role, host_role, posture, blocked_into }; confirm role: "owner" and a non-null person_id.

1. allowed_signers (optional, for local commit-signature verification): point

git config --local gpg.ssh.allowedSignersFile at a file listing the roster's keys; generate it FROM the roster so it stays in sync.

Troubleshooting matrix

Cross-references

• commands/whoami.md — the /whoami --enroll-genesis ceremony this skill operationalizes.
• rules/enrollment-operations.md — the MUST-clause discipline (signing-first, codify-branch,

script-by-path, fold-clean, self-enroll, org-admin relaxation).

• rules/multi-operator-coordination.md §1/§6 + rules/knowledge-convergence.md — the trust

substrate the anchor establishes.

• agents/onboarding/coc-onboarding-specialist.md — the operator-lifecycle expert that drives

this runbook end-to-end.