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

package/runtime/pi/bin/pi-observe-context.mjs

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+
+const DEFAULT_TIMEOUT_MS = 45_000;
+
+function contextFromEnvelope(stdout) {
+  const rendered = String(stdout || "").trim();
+  if (!rendered) return "";
+  const payload = JSON.parse(rendered);
+  return String(payload?.hookSpecificOutput?.additionalContext || "").trim();
+}
+
+/**
+ * Enter the runtime-neutral Observe boundary without putting the user's prompt
+ * in argv, an environment variable, or a temporary file. The prompt is sent
+ * only over the child process stdin expected by bin/observe-context.sh.
+ */
+export function compileObserveContext({ root, harness, prompt, signal, timeoutMs } = {}) {
+  const projectRoot = String(root || process.cwd());
+  const runtime = String(harness || "pi");
+  const input = JSON.stringify({ prompt: String(prompt || "") }) + "\n";
+  const configuredTimeout = Number(
+    timeoutMs || process.env.EGREGORE_OBSERVE_TIMEOUT_MS || DEFAULT_TIMEOUT_MS,
+  );
+  const timeout = Number.isFinite(configuredTimeout) && configuredTimeout > 0
+    ? configuredTimeout
+    : DEFAULT_TIMEOUT_MS;
+
+  return new Promise((resolve) => {
+    const child = spawn("bash", [join(projectRoot, "bin", "observe-context.sh"), runtime], {
+      cwd: projectRoot,
+      env: {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: projectRoot,
+        EGREGORE_ROOT: projectRoot,
+        EGREGORE_RUNTIME: runtime,
+      },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let settled = false;
+    let timer;
+    const finish = (value = "") => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener?.("abort", abort);
+      resolve(value);
+    };
+    const abort = () => {
+      try { child.kill("SIGTERM"); } catch {}
+      finish("");
+    };
+    timer = setTimeout(abort, timeout);
+    signal?.addEventListener?.("abort", abort, { once: true });
+    if (signal?.aborted) return abort();
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.resume();
+    child.on("error", () => finish(""));
+    child.on("close", (code) => {
+      if (code !== 0) return finish("");
+      try { finish(contextFromEnvelope(stdout)); } catch { finish(""); }
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(input);
+  });
+}
+
+/** Register the real per-prompt extension boundary shared by Pi and Prime. */
+export function registerObserveHook(pi, { root, harness, shouldObserve } = {}) {
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (shouldObserve && !shouldObserve(event, ctx)) return;
+    const context = await compileObserveContext({
+      root,
+      harness,
+      prompt: event.prompt,
+      signal: ctx?.signal,
+    });
+    if (!context) return;
+    return {
+      message: {
+        customType: "egregore-org-context",
+        content: context,
+        display: false,
+        details: {
+          source: "EgregoreRuntime.observe",
+          harness: String(harness || "pi"),
+        },
+      },
+    };
+  });
+}

package/runtime/pi/bin/pi-product-workflows.mjs

@@ -280,7 +280,7 @@ export async function createHandoff(pi, root, params, signal) {
     await checkedExec(
       pi,
       "bash",
-      ["-c", shell, "egregore-pi-handoff", temp, body, join(root, "bin", "capture-run.sh"), ...runnerArgs],
+      ["-c", shell, "egregore-pi-handoff", temp, body, join(root, "bin", "artifact-writeback.sh"), ...runnerArgs],
       { signal, timeout: 180000 },
       "Handoff",
     );

package/runtime/pi/bin/pi-render-spec.mjs

@@ -128,7 +128,7 @@ if (check) {
   const currentOutput = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
   const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, "utf8") : "";
   if (currentOutput !== rendered || currentManifest !== manifest) {
-    console.error("pi spec out of date — run: node bin/pi-render-spec.mjs");
+    console.error("pi spec out of date — run: bash bin/node-run.sh bin/pi-render-spec.mjs");
     process.exit(1);
   }
   console.log("pi spec up to date");

package/runtime/pi/bin/post-update.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Post-update migrations for Egregore framework.
+#
+# This script is synced from upstream on every /update. All migration
+# logic lives here — not in the /update skill itself. This avoids the
+# chicken-and-egg problem: the dumb syncer pulls this script, then
+# this script handles whatever needs to happen.
+#
+# Migrations must be idempotent — they run on every update.
+
+set -euo pipefail
+
+MIGRATED=0
+
+# --- Migration: commands → skills (CC 2.0+) ---
+# CC 2.0 dropped .claude/commands/ support. If skills exist (synced from
+# upstream) and commands still exist locally, remove commands to prevent
+# duplicate entries in the slash menu.
+if [ -d ".claude/skills" ] && [ -d ".claude/commands" ]; then
+  CC_MAJOR=$(claude --version 2>/dev/null | grep -oE '^[0-9]+' || echo "0")
+  if [ "${CC_MAJOR:-0}" -ge 2 ]; then
+    git rm -r .claude/commands/ 2>/dev/null || rm -rf .claude/commands/
+    echo "  ✓ Removed .claude/commands/ (migrated to skills)"
+    MIGRATED=1
+  fi
+fi
+
+# --- Future migrations go here ---
+# Each migration should:
+# 1. Check if it needs to run (idempotent guard)
+# 2. Do the work
+# 3. Echo a status line
+# 4. Set MIGRATED=1
+
+if [ "$MIGRATED" -eq 0 ]; then
+  echo "  ✓ No migrations needed"
+fi

package/runtime/pi/bin/prime-render-spec.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Derive Prime Agent's project-local system appendix from the generated Codex
+// protocol. CLAUDE.md remains canonical:
+// CLAUDE.md -> AGENTS.md -> .prime/agent/APPEND_SYSTEM.md.
+// The second hop deliberately reuses the reviewed shell-runtime translation,
+// then adapts only the harness surfaces that differ between Codex and Prime.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const SOURCE = path.join(ROOT, "AGENTS.md");
+const OUTPUT = path.join(ROOT, ".prime", "agent", "APPEND_SYSTEM.md");
+const MANIFEST = path.join(ROOT, ".prime", "agent", "spec-manifest.json");
+const CODEX_BEGIN = "<!-- BEGIN GENERATED EGREGORE CODEX SPEC";
+const CODEX_END = "<!-- END GENERATED EGREGORE CODEX SPEC -->";
+
+function hash(value) {
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function extractSpec(source) {
+  const begin = source.indexOf(CODEX_BEGIN);
+  const contentStart = source.indexOf("\n", begin);
+  const end = source.indexOf(CODEX_END, contentStart);
+  if (begin < 0 || contentStart < 0 || end < 0) {
+    throw new Error("AGENTS.md does not contain the generated Codex spec");
+  }
+  return source.slice(contentStart + 1, end).trim();
+}
+
+function replaceSection(markdown, heading, body) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  return `${markdown.slice(0, start)}${marker}\n\n${body}${markdown.slice(end)}`;
+}
+
+// Keep an inherited section and put runtime-specific framing in front of it.
+// Command Awareness is the case that matters: the canonical category rows and
+// disambiguation map live in CLAUDE.md, and a full replace here silently
+// shipped a truncated copy that drifted for months. The Codex spec opens the
+// section with its own skills-not-slash-commands paragraph, which is wrong for
+// a runtime that does have slash commands, so that one paragraph is dropped.
+function prependToSection(markdown, heading, body, dropLeadParagraphStartingWith) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  let inherited = markdown.slice(start + marker.length, end).trim();
+  if (dropLeadParagraphStartingWith) {
+    if (!inherited.startsWith(dropLeadParagraphStartingWith)) {
+      throw new Error(`prime-render-spec: "${heading}" no longer opens with "${dropLeadParagraphStartingWith}" — the Codex wording moved; update this adaptation`);
+    }
+    inherited = inherited.slice(inherited.indexOf("\n\n") + 2).trim();
+  }
+  return replaceSection(markdown, heading, `${body}\n\n${inherited}`);
+}
+
+const CODEX_COMMAND_LEAD = "Codex reserves leading";
+
+function adapt(sourceSpec) {
+  // Anchored replacements: every `from` string MUST exist in the generated
+  // Codex spec — a missing anchor no-ops silently and drops Prime-specific
+  // wording (see the tool_call gate incident). Fail the render loudly instead.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Prime Agent"],
+    ["Codex-native", "Prime-native"],
+    ["Codex sessions", "Prime Agent sessions"],
+    ["On Codex", "On Prime Agent"],
+    ["Codex has no", "Prime Agent has no built-in"],
+    ["bin/codex-session-start.sh", "bin/prime-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".prime/agent/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded from the project-local extension)"],
+    ["If this Codex build does not support hooks", "If Prime Agent project extensions are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.prime/agent/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`prime-render-spec: anchor not found in generated Codex spec: "${from}" — the Codex wording moved; update this replacement`);
+    }
+    text = text.replaceAll(from, to);
+  }
+  text = text
+    .replace(/`\$([a-z][a-z0-9-]*)/g, "`/$1")
+    .replace(/\$([a-z][a-z0-9-]*)/g, "/$1");
+
+  text = replaceSection(text, "Egregore on Prime Agent", `You are Prime Agent running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Prime Agent resources, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
+
+This appendix is generated from the reviewed shell-runtime translation of \`CLAUDE.md\`, the behavioral source of truth. Prime Agent loads it through \`.prime/agent/APPEND_SYSTEM.md\`. Egregore workflows are shared from \`.codex/skills/\` through the Agent Skills standard (via \`.agents/skills\` and project settings) and exposed as familiar slash commands by \`.prime/agent/extensions/egregore.ts\`.
+
+Your subagent mechanism (\`rlm(...)\`) spawns Prime Agent child sessions, not Egregore Loom lanes. Ignore Loom routing preambles inside shared skills: run those workflows inline.`);
+
+  text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Prime Agent extension renders the Egregore startup card (identity, handoffs, team activity) inside the session via \`bin/prime-session-start.sh\`. This works for direct \`prime-agent\` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Prime Agent, run \`bash bin/prime-session-start.sh --card\`.`);
+
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Prime Agent slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.prime/agent/extensions/egregore.ts\`; the duplicate \`/skill:name\` listings are disabled so each workflow appears once. Natural-language requests work normally — and are the route for any workflow whose name collides with a Prime Agent built-in: **say "update egregore" rather than typing \`/update\`**, which is Prime Agent's own self-updater. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
+
+Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Prime Agent, run referenced \`bin/\` scripts through the IPython kernel (or the bash tool when active), use ordinary shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no UI question surface is available.
+
+The \`egregore\` Python-backed skill exposes the mechanics as kernel functions — \`import egregore\`, then \`egregore.search(query)\`, \`egregore.activity()\`, \`egregore.handoff(to, topic, body)\`, \`egregore.save(message, topic)\`, \`egregore.branch(topic)\`, \`egregore.notify_plan(recipient, message)\`. Prefer these over re-deriving \`bin/\` CLI usage by reading scripts. \`notify_plan\` is proposal-only: approval and dispatch always pass through the explicit human Send / Edit / Cancel checkpoint.
+
+"Get the latest changes" inside a session means \`/reload\` — it re-reads instructions, context files, skills, and extensions from disk. Never \`git pull\`, \`git reset\`, or \`git checkout\` the working branch to pick up updates. When pivoting topics inside a worktree that carries unmerged branch work, create the new branch from the current HEAD, not \`origin/{base}\` — branching from the configured base in such a worktree removes the unmerged files from disk.
+
+Kernel shell escapes can be time-capped by the harness. Egregore \`bin/\` scripts that sync git state or query the connected graph legitimately run 10–120 seconds: run them with a generous timeout (a \`%%bash\` cell, or the longest limit the harness exposes). If a command dies suspiciously fast (~5s) with partial output, treat it as a timeout — rerun once with a longer limit or render the workflow's designed one-line fallback. Never debug data plumbing inside a product workflow. Connected mode works normally here: graph reads and \`bin/search.sh\` enrichment use the instance's configured credentials, and when graph data is degraded say so in one plain line rather than narrating connectivity theories.`, CODEX_COMMAND_LEAD);
+
+  return `# Egregore on Prime Agent\n\nThis file is generated by \`bin/prime-render-spec.mjs\`; do not edit it by hand.\n\n${text}\n`;
+}
+
+const check = process.argv.includes("--check");
+const source = fs.readFileSync(SOURCE, "utf8");
+const sourceSpec = extractSpec(source);
+const rendered = adapt(sourceSpec);
+const manifest = `${JSON.stringify({
+  generatedBy: "bin/prime-render-spec.mjs",
+  source: "AGENTS.md generated Codex spec",
+  sourceHash: hash(sourceSpec),
+  outputHash: hash(rendered),
+  adaptations: [
+    "Prime Agent APPEND_SYSTEM delivery from .prime/agent/",
+    "Prime Agent tool_call branch gate incl. ipython classification",
+    "Prime Agent slash-command extension over shared portable skills",
+    "rlm() subagents are not Loom lanes; Loom preambles run inline",
+  ],
+}, null, 2)}\n`;
+
+if (check) {
+  const currentOutput = fs.existsSync(OUTPUT) ? fs.readFileSync(OUTPUT, "utf8") : "";
+  const currentManifest = fs.existsSync(MANIFEST) ? fs.readFileSync(MANIFEST, "utf8") : "";
+  if (currentOutput !== rendered || currentManifest !== manifest) {
+    console.error("prime spec out of date — run: bash bin/node-run.sh bin/prime-render-spec.mjs");
+    process.exit(1);
+  }
+  console.log("prime spec up to date");
+} else {
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, rendered);
+  fs.writeFileSync(MANIFEST, manifest);
+  console.log(`prime spec rendered: .prime/agent/APPEND_SYSTEM.md (${Buffer.byteLength(rendered)} bytes)`);
+}

package/runtime/pi/bin/publish-artifact.sh

@@ -41,6 +41,7 @@ DESCRIPTION=""
 ARTIFACT_ID=""
 RAW_HTML=0
 SKIP_REFERENCES=0
+ALLOW_ADMIN=0
 PAIR=""
 VERIFY_FIDELITY=0
 FIDELITY_SOURCE=""
@@ -55,6 +56,7 @@ while [[ $# -gt 0 ]]; do
     --verify-fidelity) VERIFY_FIDELITY=1; shift ;;
     --source) FIDELITY_SOURCE="$2"; shift 2 ;;
     --raw-html) RAW_HTML=1; shift ;;
+    --allow-admin) ALLOW_ADMIN=1; shift ;;
     --no-references) SKIP_REFERENCES=1; shift ;;
     *)
       if [ -z "$TYPE" ]; then
@@ -149,6 +151,50 @@ if [ -z "$API_URL" ] || [ -z "$API_KEY" ]; then
   fi
 fi
 
+# --- Admin-content gate (the refusal documented in bin/lib/permissions.sh) --
+# `admin: true` sources — including backtick-referenced memory files — are
+# refused before any render or upload. An authorized admin (stable identity,
+# github.username alias against egregore.json admins) may proceed only with
+# the explicit --allow-admin confirmation, which is separate from and never
+# replaces normal publication approval. This protects the Egregore surface;
+# repository members can still read raw Git files.
+# shellcheck source=bin/lib/permissions.sh
+source "$SCRIPT_DIR/bin/lib/permissions.sh"
+ADMIN_MARKED=()
+if _is_admin_only_file "$FILE"; then
+  ADMIN_MARKED+=("$FILE")
+fi
+if [ "$RAW_HTML" -eq 0 ]; then
+  while IFS= read -r ref; do
+    [ -z "$ref" ] && continue
+    rel="${ref#\`}"
+    rel="${rel%\`}"
+    if [ -f "$SCRIPT_DIR/$rel" ] && _is_admin_only_file "$SCRIPT_DIR/$rel"; then
+      ADMIN_MARKED+=("$rel")
+    fi
+  done < <(grep -Eo '`memory/[^`[:space:]]+\.(md|html)`' "$FILE" 2>/dev/null | sort -u)
+fi
+if [ "${#ADMIN_MARKED[@]}" -gt 0 ]; then
+  IS_ADMIN="false"
+  ADMIN_JSON=$(cd "$SCRIPT_DIR" && EGREGORE_ROOT="$SCRIPT_DIR" \
+    PYTHONPATH="$SCRIPT_DIR${PYTHONPATH:+:$PYTHONPATH}" \
+    python3 -m egregore_runtime.harness_cli admin-status 2>/dev/null) || true
+  IS_ADMIN=$(printf '%s' "$ADMIN_JSON" | jq -r '.admin // false' 2>/dev/null || echo "false")
+  if [ "$IS_ADMIN" != "true" ]; then
+    echo "publish refused: admin-marked content cannot be published by a non-admin member:" >&2
+    printf '  %s\n' "${ADMIN_MARKED[@]}" >&2
+    echo "(--allow-admin is available to organization admins only)" >&2
+    exit 5
+  fi
+  if [ "$ALLOW_ADMIN" -ne 1 ]; then
+    echo "publish refused: this content is admin-marked:" >&2
+    printf '  %s\n' "${ADMIN_MARKED[@]}" >&2
+    echo "re-run with --allow-admin to confirm publishing admin-marked content" >&2
+    echo "(this confirmation is separate from normal publication approval)" >&2
+    exit 5
+  fi
+fi
+
 # --- Prepare HTML ---
 TMP_HTML="/tmp/egregore-artifacts/publish-$$.html"
 mkdir -p /tmp/egregore-artifacts
@@ -191,13 +237,20 @@ else
   LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
   RENDER_ERROR="/tmp/egregore-artifacts/render-error-$$.log"
   if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-    if ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+    if ! bash "$SCRIPT_DIR/bin/node-run.sh" "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
       sed -n '1,4p' "$RENDER_ERROR" >&2
       rm -f "$RENDER_ERROR"
       exit 5
     fi
   else
-    if ! npx -y egregore-artifacts@latest "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+    # Installed published renderer only — never npx/@latest: a hidden
+    # registry fetch of a floating version is not an acceptable renderer.
+    PUBLISHED_CLI="$(command -v egregore-artifacts || true)"
+    if [ -z "$PUBLISHED_CLI" ]; then
+      echo "no artifact renderer available: the checked-out packages/egregore-artifacts is unusable and no installed egregore-artifacts was found" >&2
+      exit 5
+    fi
+    if ! bash "$SCRIPT_DIR/bin/node-run.sh" "$PUBLISHED_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
       sed -n '1,4p' "$RENDER_ERROR" >&2
       rm -f "$RENDER_ERROR"
       exit 5

package/runtime/pi/bin/quest.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="$ROOT"
+export EGREGORE_SESSION_ID="${EGREGORE_SESSION_ID:-$(cat "$ROOT/.egregore-session-id" 2>/dev/null || true)}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+exec python3 -m egregore_runtime.quest_cli "$@"

package/runtime/pi/bin/question.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Runtime-neutral shell adapter for canonical asynchronous questions.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+export EGREGORE_ROOT="${EGREGORE_ROOT:-$ROOT}"
+export PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}"
+exec python3 -m egregore_runtime.question_cli "$@"

package/runtime/pi/bin/research-ingest.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# Typed Runtime boundary for approved meeting/interview analysis packages.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+EGREGORE_ROOT="$ROOT" PYTHONPATH="$ROOT${PYTHONPATH:+:$PYTHONPATH}" \
+  exec python3 -m egregore_runtime.research_ingest_cli "$@"

package/runtime/pi/bin/restore-owned-skills.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# restore-owned-skills.sh — keep org-owned skills intact through a framework update.
+#
+# Org-owned skills are declared in egregore.json → owned_skills[]. The /update
+# overlay stamps upstream framework paths (including .claude/skills/) over the
+# working tree. This script runs AFTER the overlay and BEFORE the update
+# commit. For every owned skill name:
+#
+#   - upstream does NOT ship that name  → nothing to do (the overlay never
+#     touched it; local edits, committed or not, are left alone)
+#   - upstream DOES ship that name      → the org's committed version wins:
+#     the skill directory is reset to HEAD and the collision is reported so
+#     the org can rename theirs or explicitly adopt upstream's
+#   - collision but no committed org version → upstream's copy stays (there is
+#     nothing to restore); the report says to commit and re-run /update
+#
+# Runtime-neutral: called from every harness's update flow. Idempotent; exits
+# 0 silently when owned_skills is absent or empty.
+#
+# Usage: restore-owned-skills.sh [--upstream-ref <ref>]   (default upstream/main)
+
+set -uo pipefail
+
+UPSTREAM_REF="upstream/main"
+if [ "${1:-}" = "--upstream-ref" ] && [ -n "${2:-}" ]; then
+  UPSTREAM_REF="$2"
+fi
+
+command -v jq >/dev/null 2>&1 || exit 0
+[ -f egregore.json ] || exit 0
+git rev-parse --git-dir >/dev/null 2>&1 || exit 0
+
+OWNED=$(jq -r '.owned_skills // [] | .[]' egregore.json 2>/dev/null)
+[ -n "$OWNED" ] || exit 0
+
+while IFS= read -r name; do
+  [ -n "$name" ] || continue
+  case "$name" in
+    */*|.*|*..*|*' '*)
+      echo "  ⚠ owned_skills: invalid name '$name' — skipped" >&2
+      continue
+      ;;
+  esac
+  SKILL_PATH=".claude/skills/$name"
+
+  # Only a name collision needs work — an org-only skill is never touched by
+  # the overlay, and resetting it here would destroy uncommitted local edits.
+  if ! git ls-tree -d "$UPSTREAM_REF" -- "$SKILL_PATH" 2>/dev/null | grep -q .; then
+    continue
+  fi
+
+  if git cat-file -e "HEAD:$SKILL_PATH" 2>/dev/null; then
+    # Wipe the overlay's copy (index + tree), then restore the org's committed
+    # version. rm+checkout also drops upstream-only files inside the dir.
+    git rm -r --cached --quiet -- "$SKILL_PATH" 2>/dev/null || true
+    rm -rf "$SKILL_PATH"
+    git checkout HEAD -- "$SKILL_PATH" 2>/dev/null || true
+    echo "  ◐ owned skill '$name': upstream ships a skill with this name — kept yours."
+    echo "    Review upstream's version: git diff HEAD $UPSTREAM_REF -- $SKILL_PATH"
+  else
+    echo "  ⚠ owned skill '$name': upstream ships this name and you have no committed version — upstream's copy is in the tree. Commit yours and re-run /update to keep it."
+  fi
+done <<EOF
+$OWNED
+EOF
+
+exit 0