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

package/runtime/claude/bin/person.sh

@@ -0,0 +1,481 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Provider-independent identity spine for local state, canonical people files,
+# and the shared control plane. Neo4j is an optional derived projection.
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SCRIPT_DIR="$ROOT"
+CONFIG="$ROOT/egregore.json"
+STATE="$ROOT/.egregore-state.json"
+PERSON_PY="$ROOT/bin/person.py"
+
+# shellcheck source=bin/lib/config.sh
+source "$ROOT/bin/lib/config.sh"
+
+usage() {
+  echo 'usage: bash bin/person.sh {sync|onboard|set-name NAME|set-email EMAIL|show|backfill [--dry-run|--apply] [--include-removed]}' >&2
+  exit 2
+}
+
+authorize_identity() {
+  permission="$1"
+  resource="$2"
+  EGREGORE_ROOT="$ROOT" python3 -m egregore_runtime.identity_cli \
+    authorize-self "$permission" "$resource" >/dev/null
+}
+
+remote_config() {
+  api_url="${EGREGORE_API_URL:-$(_config_val api_url)}"
+  api_key="${EGREGORE_API_KEY:-$(_load_env_var EGREGORE_API_KEY)}"
+}
+
+sync_remote_identity() {
+  identity="$1"
+  remote_config
+
+  api_status="not-configured"
+  platform_user_id=""
+  if [ -n "$api_url" ] && [ -n "$api_key" ]; then
+    api_payload="$(printf '%s' "$identity" | jq '{
+      github_username,
+      github_id,
+      github_name,
+      github_aliases,
+      display_name,
+      email,
+      emails
+    }')"
+    api_result="$(curl -sf "${api_url}/api/user/ensure" \
+      -H "Authorization: Bearer ${api_key}" \
+      -H "Content-Type: application/json" \
+      -d "$api_payload" \
+      --max-time 10 2>/dev/null || true)"
+    api_status="$(printf '%s' "$api_result" | jq -r '.status // "failed"' 2>/dev/null || echo failed)"
+    platform_user_id="$(printf '%s' "$api_result" | jq -r '.user_id // empty' 2>/dev/null || true)"
+    if [ "$api_status" = "ok" ]; then
+      if ! printf '%s' "$api_result" | EGREGORE_ROOT="$ROOT" \
+        python3 -m egregore_runtime.identity_cli >/dev/null 2>&1; then
+        api_status="identity-reconcile-failed"
+      fi
+    fi
+  fi
+
+  # A removed membership is terminal until an admin explicitly re-invites
+  # the person. Never let startup recreate their graph membership.
+  if [ "$api_status" = "removed" ]; then
+    printf '%s' "$identity" | jq \
+      --arg platform_user_id "$platform_user_id" \
+      '. + {
+        status:"removed",
+        supabase:"removed",
+        graph:"skipped-removed",
+        platform_user_id:$platform_user_id,
+        merged_duplicates:0
+      }'
+    return 0
+  fi
+
+  params="$(printf '%s' "$identity" | jq --arg platformUserId "$platform_user_id" '{
+    personId:.person_id,
+    github:.github_username,
+    githubId:(if .github_id == null then "" else (.github_id|tostring) end),
+    fullName:.github_name,
+    displayName:.display_name,
+    primaryEmail:(.email // ""),
+    emails,
+    githubAliases:.github_aliases,
+    previousNames:.previous_names,
+    profilePath:.profile_path,
+    allowNameMatch:(
+      (.allow_name_match // false)
+      or (.source_profile // "") != ""
+      or ((.aliases_reconciled // []) | length) > 0
+    ),
+    platformUserId:$platformUserId
+  }')"
+
+  graph_enabled="${EGREGORE_GRAPH_PROJECTION:-0}"
+  graph_status="disabled"
+  if [ "$graph_enabled" = "1" ]; then
+    graph_status="failed"
+    if graph_result="$(bash "$ROOT/bin/graph.sh" query "
+    OPTIONAL MATCH (legacy:Person)
+    WHERE NOT coalesce(legacy.kind, '') IN ['external', 'identity_alias']
+      AND coalesce(legacy.status, 'active') = 'active'
+      AND legacy.ingestRef IS NULL
+      AND (
+        legacy.personId = \$personId
+        OR (\$githubId <> '' AND coalesce(toString(legacy.githubId), '') = \$githubId)
+        OR toLower(coalesce(legacy.github, '')) = toLower(\$github)
+        OR toLower(coalesce(legacy.github, '')) IN
+          [alias IN \$githubAliases | toLower(alias)]
+        OR (
+          \$allowNameMatch
+          AND legacy.personId IS NULL
+          AND legacy.githubId IS NULL
+          AND (legacy.github IS NULL OR legacy.github = '')
+          AND toLower(coalesce(legacy.name, '')) = toLower(\$displayName)
+        )
+      )
+    WITH legacy
+    ORDER BY CASE
+      WHEN legacy.personId = \$personId THEN 0
+      WHEN \$githubId <> '' AND coalesce(toString(legacy.githubId), '') = \$githubId THEN 1
+      WHEN toLower(coalesce(legacy.github, '')) = toLower(\$github) THEN 2
+      ELSE 3
+    END
+    WITH head(collect(legacy)) AS legacy
+    FOREACH (_ IN CASE WHEN legacy IS NULL THEN [] ELSE [1] END |
+      SET legacy.personId = \$personId
+    )
+    MERGE (p:Person {personId: \$personId})
+    ON CREATE SET p.joined = date()
+    SET p.github = \$github,
+        p.githubId = CASE WHEN \$githubId = '' THEN p.githubId ELSE \$githubId END,
+        p.kind = 'member',
+        p.org = \$_org,
+        p.status = 'active',
+        p.removedAt = null,
+        p.identityStatus = CASE WHEN \$githubId = '' THEN 'provisional' ELSE 'verified' END,
+        p.platformUserId = CASE WHEN \$platformUserId = '' THEN p.platformUserId ELSE \$platformUserId END,
+        p.name = \$displayName,
+        p.displayName = \$displayName,
+        p.fullName = \$fullName,
+        p.email = CASE WHEN \$primaryEmail = '' THEN p.email ELSE \$primaryEmail END,
+        p.emails = reduce(acc = coalesce(p.emails, []), value IN \$emails |
+          CASE WHEN value IN acc THEN acc ELSE acc + value END),
+        p.githubAliases = reduce(acc = coalesce(p.githubAliases, []), value IN \$githubAliases |
+          CASE WHEN value IN acc THEN acc ELSE acc + value END),
+        p.previousNames = reduce(acc = coalesce(p.previousNames, []), value IN \$previousNames |
+          CASE WHEN value IN acc THEN acc ELSE acc + value END),
+        p.profilePath = \$profilePath,
+        p.identityVersion = 1,
+        p.identityUpdatedAt = datetime()
+    WITH p
+    MATCH (o:Org {id: \$_org})
+    MERGE (p)-[:MEMBER_OF]->(o)
+    RETURN p.personId AS personId
+    " "$params" 2>/dev/null)"; then
+      if printf '%s' "$graph_result" | jq -e \
+        --arg personId "$(printf '%s' "$identity" | jq -r .person_id)" \
+        '.values[0][0] == $personId' >/dev/null 2>&1; then
+        graph_status="synced"
+      fi
+    fi
+  fi
+
+  merged_duplicates=0
+  if [ "$graph_status" = "synced" ]; then
+    duplicates="$(bash "$ROOT/bin/graph.sh" query "
+      MATCH (real:Person {personId: \$personId})
+      MATCH (duplicate:Person)
+      WHERE duplicate <> real AND (
+        duplicate.personId = \$personId
+        OR (\$githubId <> '' AND coalesce(toString(duplicate.githubId), '') = \$githubId)
+        OR toLower(coalesce(duplicate.github, '')) = toLower(\$github)
+        OR toLower(coalesce(duplicate.github, '')) IN \$githubAliases
+        OR (
+          duplicate.githubId IS NULL
+          AND duplicate.personId IS NULL
+          AND (duplicate.github IS NULL OR duplicate.github = '')
+          AND any(email IN coalesce(duplicate.emails, []) WHERE email IN \$emails)
+        )
+        OR (
+          \$allowNameMatch
+          AND
+          (duplicate.github IS NULL OR duplicate.github = '')
+          AND duplicate.personId IS NULL
+          AND toLower(coalesce(duplicate.name, '')) = toLower(\$displayName)
+        )
+      )
+      AND NOT coalesce(duplicate.kind, '') IN ['external', 'identity_alias']
+      AND coalesce(duplicate.status, 'active') = 'active'
+      AND duplicate.ingestRef IS NULL
+      RETURN DISTINCT coalesce(duplicate.github, duplicate.name) AS ref
+    " "$params" 2>/dev/null || echo '{"values":[]}')"
+    while IFS= read -r duplicate; do
+      [ -n "$duplicate" ] || continue
+      if bash "$ROOT/bin/graph-op.sh" merge-person "$(printf '%s' "$identity" | jq -r .person_id)" \
+        "$duplicate" >/dev/null 2>&1; then
+        merged_duplicates=$((merged_duplicates + 1))
+      fi
+    done < <(printf '%s' "$duplicates" | jq -r '.values[]?[0] // empty')
+  fi
+
+  status="synced"
+  [ "$api_status" = "ok" ] || status="partial"
+  if [ "$graph_enabled" = "1" ] && [ "$graph_status" != "synced" ]; then
+    status="partial"
+  fi
+  printf '%s' "$identity" | jq \
+    --arg status "$status" \
+    --arg supabase "$api_status" \
+    --arg graph "$graph_status" \
+    --arg platform_user_id "$platform_user_id" \
+    --argjson merged_duplicates "$merged_duplicates" \
+    '. + {
+      status:$status,
+      supabase:$supabase,
+      graph:$graph,
+      platform_user_id:$platform_user_id,
+      merged_duplicates:$merged_duplicates
+    }'
+}
+
+backfill_people() {
+  mode="dry-run"
+  include_removed="false"
+  shift
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --dry-run) mode="dry-run" ;;
+      --apply) mode="apply" ;;
+      --include-removed) include_removed="true" ;;
+      *) usage ;;
+    esac
+    shift
+  done
+
+  if [ "$(_detect_mode)" = "local" ]; then
+    jq -n '{status:"unavailable",reason:"person backfill requires the hosted member roster in this configuration"}'
+    return 1
+  fi
+  command -v gh >/dev/null 2>&1 || {
+    jq -n '{status:"error",error:"GitHub CLI is required to resolve stable user ids"}'
+    return 1
+  }
+
+  remote_config
+  if [ -z "$api_url" ] || [ -z "$api_key" ]; then
+    jq -n '{status:"error",error:"connected API configuration is incomplete"}'
+    return 1
+  fi
+  org_slug="$(_config_val slug)"
+  members_result="$(curl -sf "${api_url}/api/org/${org_slug}/members?include_removed=true" \
+    -H "Authorization: Bearer ${api_key}" \
+    --max-time 20 2>/dev/null || true)"
+  if ! printf '%s' "$members_result" | jq -e '.members | type == "array"' >/dev/null 2>&1; then
+    jq -n '{status:"error",error:"could not load the hosted member roster"}'
+    return 1
+  fi
+  if ! printf '%s' "$members_result" | jq -e \
+    '.members | length == 0 or all(has("github_id") and has("github_aliases"))' \
+    >/dev/null 2>&1; then
+    jq -n '{status:"blocked",error:"the hosted API is still using the pre-identity member contract; deploy it before backfilling"}'
+    return 1
+  fi
+
+  results='[]'
+  excluded_removed=0
+  while IFS= read -r member; do
+    [ -n "$member" ] || continue
+    member_status="$(printf '%s' "$member" | jq -r '.status // "active"')"
+    if [ "$member_status" != "active" ] && [ "$include_removed" != "true" ]; then
+      excluded_removed=$((excluded_removed + 1))
+      continue
+    fi
+
+    previous_github="$(printf '%s' "$member" | jq -r '.github_username // empty')"
+    if ! printf '%s' "$previous_github" | grep -Eq '^[A-Za-z0-9-]{1,39}$'; then
+      item="$(jq -n --arg github "$previous_github" '{
+        github_username:$github,status:"skipped",reason:"invalid GitHub login"
+      }')"
+      results="$(printf '%s' "$results" | jq --argjson item "$item" '. + [$item]')"
+      continue
+    fi
+
+    github_result="$(gh api "users/${previous_github}" \
+      --jq '{login,id,name,email}' 2>/dev/null || true)"
+    if ! printf '%s' "$github_result" | jq -e \
+      '.login and (.id | type == "number")' >/dev/null 2>&1; then
+      item="$(jq -n --arg github "$previous_github" '{
+        github_username:$github,status:"unresolved",reason:"GitHub identity could not be resolved"
+      }')"
+      results="$(printf '%s' "$results" | jq --argjson item "$item" '. + [$item]')"
+      continue
+    fi
+
+    github="$(printf '%s' "$github_result" | jq -r .login)"
+    github_id="$(printf '%s' "$github_result" | jq -r .id)"
+    github_name="$(printf '%s' "$github_result" | jq -r '.name // empty')"
+    public_email="$(printf '%s' "$github_result" | jq -r '.email // empty')"
+    display_name="$(printf '%s' "$member" | jq -r \
+      --arg githubName "$github_name" --arg github "$github" \
+      '.display_name // (if $githubName != "" then $githubName else $github end)')"
+    role="$(printf '%s' "$member" | jq -r '.member_role // .role // "Member"')"
+    joined="$(printf '%s' "$member" | jq -r '.joined_at // empty' | cut -c1-10)"
+    aliases="$(printf '%s' "$member" | jq -r \
+      --arg old "$previous_github" --arg current "$github" '
+      ((.github_aliases // []) + (if ($old|ascii_downcase) != ($current|ascii_downcase) then [$old] else [] end))
+      | map(select(type == "string" and length > 0)) | unique | join(",")
+    ')"
+    emails="$(printf '%s' "$member" | jq -r \
+      --arg public "$public_email" '
+      ((.emails // []) + [(.primary_email // ""), $public])
+      | map(select(type == "string" and length > 0)) | unique | join(",")
+    ')"
+
+    profile_args=(
+      sync-profile
+      --github "$github"
+      --github-id "$github_id"
+      --github-name "$github_name"
+      --display-name "$display_name"
+      --previous-github "$previous_github"
+      --github-aliases "$aliases"
+      --emails "$emails"
+      --role "$role"
+      --joined "$joined"
+    )
+    [ "$mode" = "apply" ] || profile_args+=(--dry-run)
+    if ! identity="$(python3 "$PERSON_PY" "${profile_args[@]}")"; then
+      item="$(jq -n --arg github "$github" '{
+        github_username:$github,status:"skipped",reason:"profile reconciliation failed"
+      }')"
+      results="$(printf '%s' "$results" | jq --argjson item "$item" '. + [$item]')"
+      continue
+    fi
+    roster_name_matches="$(printf '%s' "$members_result" | jq \
+      --arg displayName "$display_name" '
+      [.members[]
+        | (.display_name // "")
+        | select(length > 0)
+        | ascii_downcase
+        | select(. == ($displayName | ascii_downcase))]
+      | length
+    ')"
+    allow_name_match="false"
+    [ "$roster_name_matches" -eq 1 ] && allow_name_match="true"
+    identity="$(printf '%s' "$identity" | jq \
+      --argjson allowNameMatch "$allow_name_match" \
+      '.allow_name_match = $allowNameMatch')"
+
+    if [ "$mode" = "apply" ]; then
+      synced="$(sync_remote_identity "$identity")"
+      report="$(printf '%s' "$synced" | jq 'del(.email,.emails,.allow_name_match)')"
+    else
+      report="$(printf '%s' "$identity" | jq \
+        '. + {status:"planned"} | del(.email,.emails,.allow_name_match)')"
+    fi
+    results="$(printf '%s' "$results" | jq --argjson item "$report" '. + [$item]')"
+  done < <(printf '%s' "$members_result" | jq -c '.members[]')
+
+  printf '%s' "$results" | jq \
+    --arg mode "$mode" \
+    --arg org "$org_slug" \
+    --argjson excluded_removed "$excluded_removed" '
+    {
+      status:(if any(.[]; .status == "partial") then "partial" else "ok" end),
+      mode:$mode,
+      org:$org,
+      summary:{
+        considered:length,
+        planned_or_synced:[.[] | select(.status == "planned" or .status == "synced")]|length,
+        partial:[.[] | select(.status == "partial")]|length,
+        unresolved:[.[] | select(.status == "unresolved")]|length,
+        skipped:[.[] | select(.status == "skipped")]|length,
+        excluded_removed:$excluded_removed
+      },
+      people:.
+    }'
+}
+
+command="${1:-}"
+[ -n "$command" ] || usage
+
+if [ "$command" = "show" ]; then
+  authorize_identity read "identity:self"
+  jq '{
+    person_id,
+    display_name,
+    github_username,
+    github_id,
+    github_name,
+    email,
+    emails,
+    github_aliases,
+    previous_names,
+    identity_version
+  }' "$STATE"
+  exit 0
+fi
+
+if [ "$command" = "backfill" ]; then
+  authorize_identity administer "identity:roster"
+  backfill_people "$@"
+  exit $?
+fi
+
+display_args=()
+email_args=()
+onboard_args=()
+case "$command" in
+  sync) ;;
+  onboard) onboard_args=(--onboarded) ;;
+  set-name)
+    name="${2:-}"
+    [ -n "$name" ] || usage
+    if [ "${#name}" -gt 60 ] || ! printf '%s' "$name" | grep -Eq "^[[:alnum:]À-ž .'-]+$"; then
+      echo '{"status":"error","error":"display name must be 1-60 name characters"}'
+      exit 2
+    fi
+    display_args=(--display-name "$name")
+    ;;
+  set-email)
+    email="${2:-}"
+    [ -n "$email" ] || usage
+    if [ "${#email}" -gt 254 ] || ! printf '%s' "$email" | grep -Eq '^[^[:space:]@]+@[^[:space:]@]+\.[^[:space:]@]+$'; then
+      echo '{"status":"error","error":"email must be a valid address"}'
+      exit 2
+    fi
+    email_args=(--email "$email")
+    ;;
+  *) usage ;;
+esac
+
+# Bootstrap reconciliation is allowed to establish the first ActorContext;
+# every explicit self-service mutation must authorize before provider lookup,
+# canonical profile writes, control-plane reconciliation, or projection.
+if [ "$command" = "set-name" ] || [ "$command" = "set-email" ]; then
+  authorize_identity administer "identity:self"
+fi
+
+github_args=()
+state_github="$(jq -r '.github_username // empty' "$STATE" 2>/dev/null)"
+if command -v gh >/dev/null 2>&1; then
+  gh_identity="$(gh api user --jq '{login,id,name,email}' 2>/dev/null || true)"
+  gh_login="$(printf '%s' "$gh_identity" | jq -r '.login // empty' 2>/dev/null)"
+  gh_id="$(printf '%s' "$gh_identity" | jq -r '.id // empty' 2>/dev/null)"
+  state_github_id="$(jq -r '.github_id // empty' "$STATE" 2>/dev/null)"
+  gh_login_lc="$(printf '%s' "$gh_login" | tr '[:upper:]' '[:lower:]')"
+  state_github_lc="$(printf '%s' "$state_github" | tr '[:upper:]' '[:lower:]')"
+  if [ -n "$gh_login" ] && {
+    [ -z "$state_github" ] ||
+    [ "$gh_login_lc" = "$state_github_lc" ] ||
+    { [ -n "$gh_id" ] && [ -n "$state_github_id" ] && [ "$gh_id" = "$state_github_id" ]; }
+  }; then
+    github_args=(--github "$gh_login")
+    gh_email="$(printf '%s' "$gh_identity" | jq -r '.email // empty')"
+    [ -z "$gh_id" ] || github_args+=(--github-id "$gh_id")
+    [ -z "$gh_email" ] || github_args+=(--email "$gh_email")
+  fi
+fi
+
+if [ "$(jq -r '.onboarding_complete // false' "$STATE" 2>/dev/null)" = "true" ]; then
+  onboard_args=(--onboarded)
+fi
+# macOS still ships Bash 3.2, where expanding an empty array under `set -u`
+# raises "unbound variable". Disable nounset only for this argument expansion;
+# every value remains passed as a separately quoted argument.
+set +u
+identity="$(python3 "$PERSON_PY" sync-local \
+  "${display_args[@]}" "${github_args[@]}" "${email_args[@]}" "${onboard_args[@]}")"
+set -u
+
+if [ "$(_detect_mode)" = "local" ]; then
+  printf '%s' "$identity" | jq '. + {status:"synced-local",supabase:"unavailable",graph:"unavailable"}'
+  exit 0
+fi
+
+sync_remote_identity "$identity"

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Derive Pi's project-local system appendix from the generated Codex protocol.
+// CLAUDE.md remains canonical: CLAUDE.md -> AGENTS.md -> .pi/APPEND_SYSTEM.md.
+// The second hop deliberately reuses the reviewed shell-runtime translation,
+// then adapts only the harness surfaces that differ between Codex and Pi.
+
+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, ".pi", "APPEND_SYSTEM.md");
+const MANIFEST = path.join(ROOT, ".pi", "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(`pi/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 once no-opped silently (the tool_call gate
+  // wording vanished from this file for a whole PR cycle before a test caught
+  // it) — now it fails the render loudly so the anchor gets updated alongside
+  // the Codex text that moved.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Pi"],
+    ["Codex-native", "Pi-native"],
+    ["Codex sessions", "Pi sessions"],
+    ["On Codex", "On Pi"],
+    ["Codex has no", "Pi has no built-in"],
+    ["bin/codex-session-start.sh", "bin/pi-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".pi/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded after Pi project trust)"],
+    ["If this Codex build does not support hooks", "If Pi project resources are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.pi/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`pi-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 Pi", `You are Pi running inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, project-local Pi 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. Pi loads it through \`.pi/APPEND_SYSTEM.md\` after the launcher grants project trust for this run. Egregore workflows are shared from \`.codex/skills/\` using Pi's documented cross-harness skill support and exposed as familiar slash commands by \`.pi/extensions/egregore.ts\`.`);
+
+  text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Pi extension renders the Egregore startup card (identity, handoffs, team activity) inside Pi via \`bin/pi-session-start.sh\`. This works for direct \`pi\` 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 Pi, run \`bash bin/pi-session-start.sh --card\`.`);
+
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Pi slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.pi/extensions/egregore.ts\`. Pi also exposes the underlying Agent Skills as \`/skill:name\`, and natural-language requests work normally. \`/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 Pi, run referenced \`bin/\` scripts directly, use ordinary Pi shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no Pi UI question surface is available.`, CODEX_COMMAND_LEAD);
+
+  return `# Egregore on Pi\n\nThis file is generated by \`bin/pi-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/pi-render-spec.mjs",
+  source: "AGENTS.md generated Codex spec",
+  sourceHash: hash(sourceSpec),
+  outputHash: hash(rendered),
+  adaptations: [
+    "Pi project trust and APPEND_SYSTEM delivery",
+    "Pi tool_call branch gate",
+    "Pi slash-command extension over shared portable skills",
+    "plain-text question fallback and direct shell/network execution",
+  ],
+}, 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("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");
+} else {
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, rendered);
+  fs.writeFileSync(MANIFEST, manifest);
+  console.log(`pi spec rendered: .pi/APPEND_SYSTEM.md (${Buffer.byteLength(rendered)} bytes)`);
+}

package/runtime/claude/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