create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/lib/setup.js

@@ -12,6 +12,11 @@ const {
   installCodexRuntime,
   reportCodexRuntimeSummary,
 } = require("./codex-runtime");
+const {
+  hasClaudeRuntimeSupport,
+  installClaudeRuntime,
+  reportClaudeRuntimeSummary,
+} = require("./claude-runtime");
 const {
   hasPiRuntimeSupport,
   installPiRuntime,
@@ -27,6 +32,12 @@ const {
   reportConnectRuntimeSummary,
 } = require("./connect-runtime");
 const { commandExists } = require("./path-lookup");
+const {
+  initializeIdentityState,
+  initializeOnboardingState,
+  initializeOrganizationConfig,
+  organizationIdentityDocument,
+} = require("./runtime-identity");
 
 const https = require("node:https");
 
@@ -34,6 +45,41 @@ function run(cmd, opts = {}) {
   return execSync(cmd, { stdio: "pipe", encoding: "utf-8", timeout: 60000, ...opts }).trim();
 }
 
+function prepareLocalRetrieval(egregoreDir, ui) {
+  const adapter = path.join(egregoreDir, "bin", "agent.sh");
+  if (!fs.existsSync(adapter)) {
+    ui.warn("Local retrieval setup is unavailable; update this Egregore before indexing memory");
+    return { status: "unavailable", bm25Ready: false, semantic: "unavailable" };
+  }
+  ui.info("Preparing Local retrieval · QMD 2.8.3 · BM25 first, semantic embeddings in background…");
+  const result = spawnSync("bash", [adapter, "sync"], {
+    cwd: egregoreDir,
+    encoding: "utf-8",
+    timeout: 180000,
+    env: { ...process.env, EGREGORE_RUNTIME: "installer" },
+  });
+  const output = `${result.stdout || ""}\n${result.stderr || ""}`;
+  const bm25Ready = /lexical ready:\s*yes/i.test(output);
+  const semantic = /semantic:\s*ready/i.test(output)
+    ? "ready"
+    : /semantic:\s*building/i.test(output)
+      ? "building"
+      : "unavailable";
+  if (result.status !== 0 || !bm25Ready) {
+    const detail = output.trim().split(/\r?\n/).find((line) => /^failure:/i.test(line));
+    ui.warn(`Canonical memory is installed, but Local retrieval is not ready${detail ? ` — ${detail}` : ""}`);
+    ui.info("  Retry: egregore runtime sync");
+    return { status: "degraded", bm25Ready, semantic, output };
+  }
+  ui.success("Canonical memory current · BM25 search ready");
+  if (semantic === "ready") {
+    ui.success("Semantic retrieval ready");
+  } else {
+    ui.info("  ◐ Semantic embeddings are building in the background; search works now with BM25");
+  }
+  return { status: "ready", bm25Ready, semantic, output };
+}
+
 function ghApi(method, apiPath, token, body) {
   return new Promise((resolve, reject) => {
     const payload = body ? JSON.stringify(body) : null;
@@ -77,6 +123,7 @@ function ghApi(method, apiPath, token, body) {
 function initMemoryDirs(memoryDir) {
   const dirs = [
     "people",
+    "identity",
     "invites",
     "handoffs",
     "knowledge/questions",
@@ -99,6 +146,9 @@ function initMemoryDirs(memoryDir) {
  * Accept pending GitHub repo collaboration invitations for the given org.
  */
 async function acceptPendingInvitations(githubToken, githubOrg, ui) {
+  // Offline/local fixtures and token-less refreshes have no GitHub identity to
+  // query.  Returning here also keeps packaged-artifact canaries hermetic.
+  if (!githubToken || !githubOrg) return;
   try {
     const { status, data } = await ghApi("GET", "/user/repository_invitations", githubToken);
     if (status !== 200 || !Array.isArray(data)) return;
@@ -292,7 +342,7 @@ async function ensureInstallerMemberRole(data = {}, existingState = {}, ui) {
 }
 
 function buildOnboardingState(existing = {}, data = {}, opts = {}) {
-  const state = { ...existing };
+  let state = initializeIdentityState(existing, data, opts);
   const preferredRuntime = normalizeRuntime(opts.runtime);
   const githubUsername = data.github_username || state.github_username || "";
   const githubId = data.github_id || state.github_id || null;
@@ -359,7 +409,7 @@ function buildOnboardingState(existing = {}, data = {}, opts = {}) {
   if (data.onboarding_role || data.role) {
     state.onboarding.role = data.onboarding_role || data.role;
   }
-  return state;
+  return initializeOnboardingState(state, { ...data, display_name: displayName, member_role: memberRole });
 }
 
 async function ensureInstallerDisplayName(data, existingState, ui) {
@@ -488,8 +538,13 @@ async function install(data, ui, targetDir, opts = {}) {
   // could lose egregore.json even though the default branch contained it.
   // Recover that exact file from origin/main when possible, then validate it
   // before writing credentials or registering a launcher.
+  let runtimeConfig = null;
   if (api_key || data.api_url) {
-    ensureConnectedConfig(egregoreDir, data, ui);
+    runtimeConfig = ensureConnectedConfig(egregoreDir, data, ui);
+  } else {
+    try {
+      runtimeConfig = JSON.parse(fs.readFileSync(path.join(egregoreDir, "egregore.json"), "utf-8"));
+    } catch {}
   }
 
   // 4. Write .env (secrets only — never committed to git)
@@ -508,7 +563,12 @@ async function install(data, ui, targetDir, opts = {}) {
   }
   const displayName = await ensureInstallerDisplayName(data, state, ui);
   const memberRole = await ensureInstallerMemberRole(data, state, ui);
-  state = buildOnboardingState(state, { ...data, display_name: displayName, member_role: memberRole }, {
+  state = buildOnboardingState(state, {
+    ...data,
+    org_id: data.org_id || runtimeConfig?.org_id || `legacy-org:${data.slug || "unknown"}`,
+    display_name: displayName,
+    member_role: memberRole,
+  }, {
     runtime: preferredRuntime,
     flowVariant: opts.flowVariant,
     onboardingComplete: opts.onboardingComplete !== false,
@@ -516,13 +576,13 @@ async function install(data, ui, targetDir, opts = {}) {
   fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
   try { ensurePersonOnboardingWitness(memoryDir, state); } catch {}
 
-  // 4c. Overlay the selected shell-runtime support. Claude Code reads
-  // CLAUDE.md, not AGENTS.md; overlaying the Codex AGENTS.md/.codex into a Claude
-  // workspace gives a wandering agent a competing startup protocol (the
-  // xenocracy onboarding regression). Claude joiners keep the cloned repo as-is —
-  // any inherited AGENTS.md carries the runtime-precedence guard that redirects
-  // Claude back to CLAUDE.md.
-  if (preferredRuntime === "codex") {
+  // 4c. Overlay the selected harness adapter from the installed npm artifact.
+  // Each adapter shares the same Egregore Runtime while keeping harness files
+  // thin and independently refreshable.
+  if (preferredRuntime === "claude-code") {
+    const claudeRuntime = installClaudeRuntime(egregoreDir);
+    reportClaudeRuntimeSummary(claudeRuntime, ui);
+  } else if (preferredRuntime === "codex") {
     const codexRuntime = installCodexRuntime(egregoreDir);
     reportCodexRuntimeSummary(codexRuntime, ui);
   } else if (preferredRuntime === "pi") {
@@ -556,6 +616,11 @@ async function install(data, ui, targetDir, opts = {}) {
     } catch {}
   }
 
+  // Make canonical memory searchable before the first harness prompt. The
+  // unified Runtime sync blocks only through BM25 readiness; initial semantic
+  // embeddings are explicitly detached and continue in the background.
+  const retrieval = prepareLocalRetrieval(egregoreDir, ui);
+
   // 5. Register instance + install launcher binary
   ui.step(5, totalSteps, "Registering instance...");
   registerInstance(forkDirName, org_name, egregoreDir, preferredRuntime);
@@ -625,6 +690,9 @@ async function install(data, ui, targetDir, opts = {}) {
     telegram: telegram_group_link ? "connected" : "skipped",
     assistant: runtimeDisplay(preferredRuntime),
     command: "run egregore anytime",
+    retrieval: retrieval.bm25Ready
+      ? (retrieval.semantic === "ready" ? "BM25 + semantic ready" : "BM25 ready · semantic building")
+      : "needs retry",
   };
 
   const ui_ = require("./ui");
@@ -637,6 +705,7 @@ async function install(data, ui, targetDir, opts = {}) {
     ui.info(`${ui.green("●")} invite      ${setupSummary.invite}`);
     ui.info(`${ui.green("●")} Telegram    ${setupSummary.telegram}`);
     ui.info(`${ui.green("●")} harness     ${setupSummary.assistant}`);
+    ui.info(`${retrieval.bm25Ready ? ui.green("●") : ui.yellow("!")} retrieval   ${setupSummary.retrieval}`);
     ui.info(`${ui.green("●")} next        ${setupSummary.command}`);
     console.log("");
     ui.info(`Your workspace:`);
@@ -730,6 +799,16 @@ function ensureConnectedConfig(repoDir, data, ui) {
     config.mode = "connected";
     changed = true;
   }
+  const initialized = initializeOrganizationConfig(config, {
+    // Legacy connected configs must resolve identically for every joiner.
+    // The control plane can replace this explicit compatibility id during a
+    // coordinated migration; never mint a different local org id per clone.
+    orgId: data.org_id || config.org_id || `legacy-org:${config.slug}`,
+  });
+  if (JSON.stringify(initialized) !== JSON.stringify(config)) {
+    config = initialized;
+    changed = true;
+  }
   if (changed) {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
   }
@@ -919,6 +998,8 @@ function primeTrustArgs() {
 }
 
 function claudeLaunchArgs(egregoreDir) {
+  // Submit Egregore's intentional initial prompt so Claude opens directly into
+  // the organization start experience.
   const args = ["start"];
   const memoryLink = path.join(egregoreDir, "memory");
   try {
@@ -1170,7 +1251,16 @@ async function launchOrInstruct(egregoreDir, alias, ui, ctx = {}) {
   ui.info(`Next time, ${launcherNextStep(ui, aliasName)}`);
   console.log("");
 
-  if (runtime === "codex") {
+  if (runtime === "claude-code") {
+    const claudeRuntime = installClaudeRuntime(egregoreDir);
+    reportClaudeRuntimeSummary(claudeRuntime, ui);
+    if (!hasClaudeRuntimeSupport(egregoreDir)) {
+      ui.warn("Claude Code runtime support is incomplete; refresh this Egregore before launching.");
+      ui.info(`Run ${ui.bold(aliasName)} after updating the checkout.`);
+      console.log("");
+      return;
+    }
+  } else if (runtime === "codex") {
     const codexRuntime = installCodexRuntime(egregoreDir);
     reportCodexRuntimeSummary(codexRuntime, ui);
     if (!hasCodexCoreSupport(egregoreDir)) {
@@ -1309,11 +1399,17 @@ function appendLocalBinToRc(ui) {
  */
 async function installLauncherBinary(egregoreDir, ui) {
   const template = readLauncherTemplate();
-  const candidates = [
-    { dir: "/usr/local/bin", location: "system" },
-    { dir: "/opt/homebrew/bin", location: "system" },
-    { dir: path.join(os.homedir(), ".local", "bin"), location: "user" },
-  ];
+  // Tests, containers, and managed installations can pin the launcher to an
+  // isolated directory.  When explicitly configured, never fall through to a
+  // machine-wide path: isolation is the reason the override exists.
+  const configuredBinDir = process.env.EGREGORE_LAUNCHER_BIN_DIR;
+  const candidates = configuredBinDir
+    ? [{ dir: path.resolve(configuredBinDir), location: "user" }]
+    : [
+        { dir: "/usr/local/bin", location: "system" },
+        { dir: "/opt/homebrew/bin", location: "system" },
+        { dir: path.join(os.homedir(), ".local", "bin"), location: "user" },
+      ];
 
   let chosen = null;
   for (const c of candidates) {
@@ -1540,6 +1636,8 @@ module.exports = {
   installLauncherBinary,
   launchOrInstruct,
   buildOnboardingState,
+  initializeOrganizationConfig,
+  organizationIdentityDocument,
   ensurePersonOnboardingWitness,
   ensureInstallerMemberRole,
   embedToken,
@@ -1551,5 +1649,6 @@ module.exports = {
   ensureDevelop,
   ensureConnectedConfig,
   resolveEgregoreInstallDir,
+  prepareLocalRetrieval,
   run,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-egregore",
-  "version": "0.20.2",
-  "description": "Set up Egregore for your team in one command \u2014 installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
+  "version": "0.21.0-runtime-mvp.2",
+  "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {
     "create-egregore": "./bin/cli.js"
@@ -10,18 +10,22 @@
     "node": ">=18"
   },
   "scripts": {
-    "build:runtime": "node ../../bin/capability-distribution.mjs generate-skill-view --root ../.. && node scripts/build-runtime-bundle.mjs && node scripts/build-pi-runtime-bundle.mjs && node scripts/build-prime-runtime-bundle.mjs && node ../../api/scripts/build-connect-runtime-pack.mjs",
+    "build:runtime": "node ../../bin/capability-distribution.mjs generate-skill-view --root ../.. && node scripts/build-runtime-bundle.mjs && node scripts/build-claude-runtime-bundle.mjs && node scripts/build-pi-runtime-bundle.mjs && node scripts/build-prime-runtime-bundle.mjs && node ../../api/scripts/build-connect-runtime-pack.mjs",
+    "build:claude-runtime": "node scripts/build-claude-runtime-bundle.mjs",
     "build:pi-runtime": "node scripts/build-pi-runtime-bundle.mjs",
     "build:prime-runtime": "node scripts/build-prime-runtime-bundle.mjs",
-    "test": "node ../../bin/capability-distribution.mjs validate --root ../.. && node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node scripts/build-prime-runtime-bundle.mjs --check && node ../../bin/prime-render-spec.mjs --check && node ../../bin/pi-render-spec.mjs --check && node ../../api/scripts/build-connect-runtime-pack.mjs --check && node --test test/capability-distribution.test.js test/connect-runtime.test.js test/context.test.js test/path-lookup.test.js test/nixos-portability.test.js test/parse-join-target.test.js test/skip-repos.test.js test/install-origin-guard.test.js test/onboarding-shortcircuit.test.js test/welcome-screen.test.js test/runtime-selection.test.js test/command-generation.test.js test/auth-gh.test.js test/gauntlet-fixes.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/prime-runtime.test.js test/prime-branch-policy.test.js test/prime-bridge-skill.test.js test/prime-session-smoke.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/scroll-repro.test.js test/launcher-refocus-redraw.test.js test/multiselect-remote-search.test.js test/back-navigation.test.js test/manifest-form.test.js test/launcher-delete.test.js test/launcher-connect.test.js test/installer-connect-choice.test.js test/launcher-connected-status.test.js test/launcher-permissions.test.js test/launcher-update.test.js test/connected-config.test.js test/workflow-settings.test.js",
+    "test": "node ../../bin/capability-distribution.mjs validate --root ../.. && node scripts/build-runtime-bundle.mjs --check && node scripts/build-claude-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node scripts/build-prime-runtime-bundle.mjs --check && node ../../bin/prime-render-spec.mjs --check && node ../../bin/pi-render-spec.mjs --check && node ../../api/scripts/build-connect-runtime-pack.mjs --check && node --test test/capability-distribution.test.js test/connect-runtime.test.js test/context.test.js test/path-lookup.test.js test/nixos-portability.test.js test/parse-join-target.test.js test/skip-repos.test.js test/install-origin-guard.test.js test/onboarding-shortcircuit.test.js test/runtime-identity.test.js test/welcome-screen.test.js test/runtime-selection.test.js test/command-generation.test.js test/auth-gh.test.js test/gauntlet-fixes.test.js test/claude-runtime.test.js test/codex-runtime.test.js test/pi-runtime.test.js test/prime-runtime.test.js test/prime-branch-policy.test.js test/prime-bridge-skill.test.js test/pi-observe-context.test.js test/pi-session-smoke.test.js test/prime-session-smoke.test.js test/pi-product-workflows.test.js test/installer-runtime-source.test.js test/runtime-readiness.test.js test/scroll-repro.test.js test/launcher-refocus-redraw.test.js test/multiselect-remote-search.test.js test/back-navigation.test.js test/manifest-form.test.js test/launcher-delete.test.js test/launcher-connect.test.js test/installer-connect-choice.test.js test/launcher-connected-status.test.js test/launcher-telemetry.test.js test/launcher-runtime.test.js test/launcher-settings.test.js test/launcher-permissions.test.js test/launcher-update.test.js test/connected-config.test.js test/workflow-settings.test.js",
+    "test:packed-runtime": "node scripts/packed-runtime-canary.mjs",
     "test:e2e": "node --test test/e2e-local.test.js",
-    "test:all": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/"
+    "test:all": "node scripts/build-runtime-bundle.mjs --check && node scripts/build-claude-runtime-bundle.mjs --check && node scripts/build-pi-runtime-bundle.mjs --check && node --test test/"
   },
   "files": [
     "bin/",
     "lib/",
     "assets/",
-    "runtime/"
+    "runtime/",
+    "!runtime/**/__pycache__/",
+    "!runtime/**/*.py[cod]"
   ],
   "keywords": [
     "egregore",

package/runtime/claude/.claude/context/commit-format.md

@@ -0,0 +1,110 @@
+# Commit Format — one convention, every harness
+
+Every commit in an Egregore — from Claude Code, Codex, Pi, a background
+script, or a human — carries the same message shape. Commits are the
+finest-grained record the org keeps: agents reconstruct context from
+`git log` before they read anything else, and a message that cannot be
+understood without its session is context lost.
+
+This spec covers newly authored, non-merge commits. Git-generated
+messages — merges, `git revert`'s native `Revert "…"` form, autosquash
+fixups — keep their native shape, and the advisory lint skips them.
+
+Sibling spec: `.claude/context/pr-format.md`. Wording rules for both:
+`.claude/context/git-language.md`.
+
+## Subject
+
+`type(scope): imperative summary` — the same grammar as PR titles
+(`pr-format.md` § Title is the authoritative statement; restated here).
+
+- ≤ 72 characters (git tooling truncates beyond that), aim for ≤ 50.
+  No trailing period.
+- Types: `feat` `fix` `docs` `refactor` `chore` `test` `perf` `ci`
+  `build` `release` — the same set as PR titles.
+- Scope = subsystem (`loom`, `emissary`, `handoff`, `api`, `site`,
+  `launcher`, …), the same vocabulary as PR titles. Omit it when the
+  summary already names the subsystem, when the change spans several,
+  or when none fits.
+- Imperative, lowercase summary. It completes "if applied, this commit
+  will ___": `fix(emissary): stop smokes emailing recipients` — not
+  `Fixed smokes` or `fixes smokes`.
+- A breaking change appends `!` after the scope
+  (`feat(api)!: drop v1 handoff routes`) and explains the break in the
+  body.
+- One logical change per commit — split when the parts are
+  independently revertable. A summary that needs "and" is the usual
+  smell, not the law.
+
+## Body
+
+Blank line after the subject, then prose wrapped at 72 columns. Never
+break a URL, command, or quoted error string to satisfy the wrap.
+
+- Optional when the subject says everything (typo fixes, mechanical
+  renames). Required when the diff cannot explain its own motivation.
+- What changed and why. State prior behavior, what was wrong with it,
+  and why this solution. Skip implementation narration the diff
+  already shows; do include mechanism that affects review, operation,
+  or compatibility.
+- Wording follows `.claude/context/git-language.md`.
+
+## Trailers
+
+Agent-authored commits end with machine-readable git trailers,
+blank-line separated from the body:
+
+```
+Egregore-Session: <session id>
+Co-Authored-By: <harness identity>
+```
+
+- `Egregore-Session` is the id from `.egregore-session-id`. It links
+  the commit to its session in the graph — commit → session → handoff
+  lineage becomes queryable:
+  `git log --format='%(trailers:key=Egregore-Session,valueonly)'`.
+  Omit only when no session id exists (bare scripts, CI). A commit
+  carrying work from several sessions repeats the trailer, one per
+  session; squashes keep every contributing session's trailer, and a
+  cherry-pick keeps the source commit's.
+- `Co-Authored-By` is the harness's standing identity line — e.g.
+  `Claude Fable 5 <noreply@anthropic.com>`, the Codex worker identity,
+  or `Egregore Attendant <noreply@egregore.xyz>`. It states that an
+  agent co-authored the commit; GitHub rendering it as a co-author is
+  the point, not a side effect.
+- Issue references are trailers (`Refs: #123`), never subject text.
+  `Refs:` is non-closing metadata; use `owner/repo#123` across repos.
+  GitHub closing keywords belong in the PR body, not in commits.
+- Humans committing by hand skip trailers.
+
+## Automation
+
+Background scripts use the same grammar — imperative, and
+`chore(<subsystem>)` unless a more specific type applies:
+
+| Legacy style | Convention |
+|---|---|
+| `Handoff: <topic> (to <who>)` | `chore(handoff): record <topic> (to <who>)` |
+| `Auto-save: session content` | `chore(autosave): save session work` |
+| `Archive session <id>` | `chore(transcripts): archive session <id>` |
+| `Auto-update Egregore framework` | `chore(sync): update framework from upstream` |
+
+Workflow scopes name workflow artifacts only. A commit that carries
+real work derives its type and scope from the diff — `/save` of a loom
+feature is `feat(loom): …`, never `chore(save): …`. The transport must
+not mask the work.
+
+## Relationship to PRs
+
+The PR title always describes the whole PR. When the PR holds a single
+commit whose subject already does that, reuse the subject verbatim —
+this is the common case for agent PRs.
+
+## Enforcement map
+
+| Layer | Path | Covers |
+|---|---|---|
+| Authoring | `.claude/skills/commit`, `/save`, `/pr`, AGENTS.md § Commit format | Claude Code, Codex, Pi, shell agents |
+| Composers | `bin/agent.sh`, `bin/handoff-*.sh`, `bin/lib/git-sync.sh`, `bin/session-autosave.sh`, … | every scripted commit |
+| Advisory CI | `.github/workflows/pr-format.yml` commit-subject report | every PR branch |
+| Parity | convention parity test (`tests/`) | spec copies across runtimes, and the grammar shared by this spec and `pr-format.md` |

package/runtime/claude/.claude/context/git-language.md

@@ -0,0 +1,46 @@
+# Git Language — how commits and PRs are worded
+
+Ten rules for the prose inside commit messages and PR bodies. Distilled
+from Simplified Technical English (ASD-STE100) and the Google developer
+documentation style guide, tuned for Egregore's actual reader: a
+teammate or an agent months from now, holding only the message and the
+diff.
+
+Structure (sections, subjects, lengths) lives in
+`.claude/context/commit-format.md` and `.claude/context/pr-format.md`.
+This file governs wording only — specifically, prose that *describes
+the change*. Subjects follow the format specs' imperative grammar, and
+procedure belongs where the format specs ask for it: verification
+commands, manual steps, migration and rollback notes are welcome in
+`## Verification` and `## Risk`, and rules 5 and 10 do not apply to
+them.
+
+1. **Active voice, named actor.** "The gate skips drafts" — not
+   "drafts are skipped."
+2. **Present tense for the change; past tense only for old behavior.**
+   "Routes /commit to the executor tier. Previously every call went to
+   the frontier model."
+3. **One fact per sentence.** Two facts are two sentences. Aim for
+   20 words or fewer.
+4. **One name per thing.** Use the org's established term every time,
+   never a synonym for variety. If the org says "handoff", then
+   "session summary" is a different thing or a mistake.
+   (`.claude/rules/voice-bedrock.md` lists banned vocabulary.)
+5. **What and why, never how.** The diff is the how. Spend words on
+   prior behavior, the problem, and why this solution.
+6. **Concrete over abstract.** Name the file, the command, the error
+   string, the number. "Cuts session start 24s → 4s" beats
+   "significantly improves performance."
+7. **Front-load.** Strongest fact first — in the subject, in each
+   bullet, in each paragraph. Readers scan.
+8. **Self-contained.** No session-local shorthand, no "as discussed",
+   no bare "it" pointing outside the message. Every reference resolves
+   from the message alone; link what you cite.
+9. **No filler.** Delete intensifiers and hedges: simply, just, very,
+   significantly, comprehensive, robust, might potentially.
+10. **Describe the change, not your process.** "Validate input before
+    parsing" — not "addressed review feedback" or "updated per
+    discussion."
+
+The test for any sentence: could an agent with no memory of this
+session act on it correctly? If not, add the missing name or number.

package/runtime/claude/.claude/context/notification-consent.md

@@ -0,0 +1,66 @@
+# External notification consent
+
+This protocol applies to every Telegram, Teams, or other external notification
+in every harness. It applies even when the user asked to announce, notify,
+handoff, invite, or message someone, and even when the harness is running with
+broad tool permissions.
+
+## Invariant
+
+Never dispatch an external notification until the human has approved that one
+exact delivery in a dedicated checkpoint. The checkpoint must show:
+
+- the organization;
+- the final recipient or group;
+- every channel that will receive it;
+- the exact final message, including links.
+
+A workflow request, plan approval, batch approval, prior approval, broad
+permission mode, or approval of a related action is not notification consent.
+There is no standing "always allow" choice. One approval authorizes one attempt
+to send one immutable message.
+
+## Required flow
+
+1. Finish the message first. Publish any artifact and insert its real URL
+   before planning; never change the message after preview.
+2. Resolve the exact delivery without sending:
+
+   ```bash
+   PLAN_JSON=$(bash bin/notify.sh plan send "$RECIPIENT" "$MESSAGE")
+   # or
+   PLAN_JSON=$(bash bin/notify.sh plan group "$MESSAGE")
+   ```
+
+3. Read `plan_id` and `digest` from `PLAN_JSON`. Show the organization,
+   recipient, all `channels`/`deliveries`, and exact `message` in a dedicated
+   Send / Edit / Cancel question. Use the harness's structured question UI
+   when available. Otherwise show the same fields in plain text and stop for
+   the user's answer.
+4. Only if the user selects Send for that exact preview:
+
+   ```bash
+   APPROVAL_JSON=$(bash bin/notify.sh approve \
+     "$PLAN_ID" "$DIGEST" APPROVE_EXACT_NOTIFICATION)
+   APPROVAL_TOKEN=$(printf '%s' "$APPROVAL_JSON" | jq -r '.approval_token')
+   bash bin/notify.sh dispatch "$PLAN_ID" "$APPROVAL_TOKEN"
+   ```
+
+5. If the user chooses Edit, cancel the old plan, edit, create a new plan, and
+   preview again. If they choose Cancel, cancel it and do not send. If the plan
+   expires or dispatch fails, create a new plan and obtain new consent; never
+   retry from the old approval.
+
+## Hard rules
+
+- Never call notification API endpoints directly. Use `bin/notify.sh`.
+- Never use legacy `notify.sh send` or `notify.sh group`; they only create a
+  proposal and intentionally cannot dispatch.
+- Never substitute a group when a direct message cannot be delivered.
+- Never add a channel after preview.
+- Never approve or dispatch from a detached/background process, hook, cron
+  job, batch execution, or unattended agent. Those paths may create a plan and
+  report that human approval is pending.
+- Multiple direct recipients require a separate preview and approval for each
+  exact message. A group fanout may use one approval only when every receiving
+  channel is listed in the preview.

package/runtime/claude/.claude/context/pr-format.md

@@ -0,0 +1,67 @@
+# PR Format — one convention, every harness
+
+Every pull request in an Egregore — from Claude Code, Codex, any other
+harness, a script, or a human — carries the same description shape. Domain
+knowledge encoded as infrastructure, not as per-harness habit. It is
+enforced in four layers: authoring instructions (this spec, referenced by
+`/pr`, `/save`, and AGENTS.md), a fallback generator (`bin/agent.sh save`
+builds a compliant body when the caller supplies none), a web-UI template
+for humans, and a CI gate (`.github/workflows/pr-format.yml`) that fails
+non-compliant PRs with a fix-it comment.
+
+Sibling spec: `.claude/context/commit-format.md` (commit subjects share
+this spec's title grammar). Wording rules for both:
+`.claude/context/git-language.md`.
+
+## Title
+
+`type(scope): imperative summary` — ≤ 72 chars, no trailing period.
+Types: `feat` `fix` `docs` `refactor` `chore` `test` `perf` `ci` `build`
+`release`. Scope = subsystem (`loom`, `minion`, `emissary`, `api`, `site`,
+`launcher`, …). Title style is advisory — reported by the gate, not failed.
+
+## Body
+
+Three sections are gated, two are optional. In this order:
+
+| Section | Required | Contents |
+|---|---|---|
+| `## What` | always | 1–4 bullets, the change itself, most important first. A reader should know what merged from this section alone. |
+| `## Why` | always | 1–3 sentences. The motivation or problem — context the diff cannot show. Link the decision/quest/issue that spawned it. |
+| `## Verification` | when the diff touches non-markdown files | How this was checked: test command + result, manual steps, or an honest `Not verified — <reason>`. Never omit; never fake. The gate accepts `## Testing` as a legacy alias — write `## Verification` in new PRs. |
+| `## Risk` | when real | Breaking changes, blast radius (does merging publish or deploy?), rollback note. |
+| `## Links` | when they exist | Issues, quests, handoffs, superseded PRs. |
+
+Footer: the attribution line of the harness that authored the body —
+one line, the final non-blank line, preceded by a blank line, shaped
+`🤖 <verb> with/via <harness>`. Canonical forms:
+`🤖 Generated with [Claude Code](https://claude.com/claude-code)`,
+`🤖 Generated with Codex`. The transport form (`🤖 Saved via
+bin/agent.sh`) appears only when the bridge generated the skeleton
+body itself. Humans skip the footer. Commit-level attribution is
+separate and lives in git trailers — see
+`.claude/context/commit-format.md` § Trailers.
+
+## Rules of thumb
+
+- **Compact beats complete.** Drop a detail if it doesn't change what the
+  reviewer does next. Hierarchy beats prose: lead each section with its
+  strongest line.
+- **Never create a PR with an empty body** or `--fill`. A harness that
+  cannot write the body routes through `bin/agent.sh save`, which generates
+  a compliant skeleton from the commit log and diff.
+- **Auto-merged markdown-only PRs still need What + Why** — two lines
+  suffice.
+
+## Enforcement map
+
+| Layer | Path | Covers |
+|---|---|---|
+| Authoring | `.claude/skills/pr`, `.claude/skills/save`, `AGENTS.md` § Pull request format | Claude Code, Codex, shell agents |
+| Fallback generator | `bin/agent.sh save` (`--pr-body` / auto-skeleton) | any bridge caller |
+| Template | `.github/pull_request_template.md` | humans in the web UI |
+| Gate | `.github/workflows/pr-format.yml` | everything — fails the check and posts a fix-it comment |
+
+Gate exemptions: draft PRs, `release:`-titled PRs, bot-authored PRs.
+The gate blocks auto-merge only if `pr-format` is marked a required status
+check in branch protection — an admin, per-repo setting.