create-egregore 0.21.6 → 0.22.0

package/runtime/pi/AGENTS.md

@@ -38,11 +38,6 @@ Internal handoffs use `bin/agent.sh handoff` (`memory/handoffs/` + index,
 via `bin/handoff-run.sh`). External capsules use `egregore-emissary`.
 Never use deprecated `egregore-handoff` for internal handoffs.
 
-## Compatibility
-
-Claude Code follows `CLAUDE.md`; other shell agents use the generated
-contract below. All runtimes share canonical memory.
-
 <!-- BEGIN GENERATED EGREGORE CODEX SPEC — derived from CLAUDE.md by bin/codex-render-spec.mjs; do not edit by hand -->
 
 ## Egregore on Codex
@@ -77,13 +72,14 @@ When a user reports broken or missing framework behavior, the first question is
 
 ## Cross-Runtime Compatibility
 
-Framework behavior must work across Claude Code, Codex, and Pi Egregores. Put
-shared mechanics in runtime-neutral `bin/` scripts; keep `.claude/`, `.codex/`,
-and `.pi/` as thin adapters to those mechanics. When changing startup, session
-lifecycle, capture, skills, or commands, trace all three runtime entry points
-and add or update a parity test. Do not call a framework change complete based
-on one runtime alone. Regenerate derived Codex and Pi specifications or runtime
-bundles whenever their sources change.
+Share `bin/` mechanics through thin Claude/Codex/Pi/Prime adapters. Startup,
+lifecycle, capture, skill and command changes require tracing every runtime,
+parity tests and regenerated specs/bundles before completion.
+
+Discover via `bash bin/spirit-discovery-codex.sh capabilities.list` (Pi/Prime:
+registered tool). Follow `docs/spirit-discovery.md`: keep seven facets separate;
+generic shell needs one snapshot. Discovery reads code/install evidence, not
+memory, and grants no authority.
 
 ---
 
@@ -142,25 +138,7 @@ For continued project work: **continuation intent → prior workspace → restor
 
 ### Handoff claiming
 
-If `addressed_to_user` handoffs exist and the user is picking one up, create the IMPLEMENTS link after branch creation:
-```bash
-bash bin/graph-op.sh claim-handoff "$SESSION_ID" "$HANDOFF_SESSION_ID" 2>/dev/null &
-```
-
-**Auto-checkout repos from handoff**: after claiming, if `addressed_rich` carries a non-empty `repoState`, check out each entry's branch in its managed repo:
-
-```bash
-PARENT_DIR="$(cd .. && pwd)"
-# For each entry in repoState:
-REPO_DIR="$PARENT_DIR/$REPO_NAME"
-if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
-  git -C "$REPO_DIR" fetch origin "$BRANCH" --quiet 2>/dev/null
-  git -C "$REPO_DIR" checkout "$BRANCH" 2>/dev/null || \
-    git -C "$REPO_DIR" checkout -b "$BRANCH" "origin/$BRANCH" 2>/dev/null
-fi
-```
-
-Report `✓ Checked out {branch} in {repo1}, {repo2}`; for a merged-away branch, `◐ {repo}: PR #{N} merged — on {base}`. If `repoState` is absent or empty, skip silently.
+When the user picks up a handoff addressed to them, follow `.claude/context/handoff-claiming.md` after branch creation: it claims the handoff and checks out the branches its `repoState` names in each managed repo.
 
 **Exceptions** — skip branching when the user explicitly created or named a branch themselves, or the intent continues the current working branch's topic.
 
@@ -221,7 +199,7 @@ answers it: `open-handoffs`, `pending-questions`, `lineage`, or
 `meeting-history`. Verify projection freshness/coverage and open its canonical
 `evidencePath` before acting. Canonical Markdown wins on disagreement.
 
-Run `catalog` only when the route is unclear. Named reads return bounded stable fields and exact canonical `evidencePath` pointers; open only the returned files needed to answer. When a read reports partial coverage, use `unprojectedPaths` rather than claiming those files are represented in the graph. Use `bin/graph.sh` for unsupported Neo4j queries and never construct curl calls directly. See DEVELOPMENT.md §1 for the schema. Local recall uses Runtime `find`/`open`.
+Run `catalog` only when the route is unclear. Open only the returned `evidencePath` files needed to answer; on partial coverage, name `unprojectedPaths` instead of claiming them. Use `bin/graph.sh` for unsupported Neo4j queries and never construct curl calls directly (schema: DEVELOPMENT.md §1).
 
 ---
 
@@ -234,60 +212,42 @@ For each user-directed organizational lookup, show exactly one visible line:
 - retrieval that actually queries the connected graph:
   `⌕ Egregore Connect · searching your organization’s memory and relationships`
 
-When `EGREGORE_ORG_CONTEXT_V1` is attached, reuse its authorized evidence.
-For a remaining gap continue a Runtime investigation, preserving earlier findings.
-Follow `.claude/context/retrieval-investigation.md`: the model chooses keyword,
-semantic, hybrid, filename, literal, or date inventory; Runtime owns permissions,
-evidence history, pages and per-prompt limits. Empty results allow refinements
-within the requested dates. Never relax the date boundary to manufacture coverage.
-
-**Scope.** Egregore Runtime is for organizational recall only: team memory,
-decisions, handoffs, prior work. Code, files, Git, and tests use the harness's
-normal tools, with no beat and no Runtime call.
-
 **Visibility is the contract.** Emit it verbatim as a standalone assistant
 message before the first tool call that performs the organizational recall
 (the `bin/search.sh` query or a graph read). Tool output does not satisfy it.
-Do not paraphrase the line.
+Do not paraphrase the line. Emit once per episode.
+Never name `Egregore Connect` unless a graph read will actually run.
 
-Use Connect only for a graph traversal that actually runs. Emit once per
-episode.
+**Scope.** Egregore Runtime is for organizational recall only: team memory,
+decisions, handoffs, prior work. Code, files, Git, and tests use the harness's
+normal tools, with no beat and no Runtime call. Startup hydration, graph
+writes, ingestion, background sync, maintenance, and internal queries get no beat.
 
 **Routing:** Organizational recall always enters Egregore Runtime. The model is
 the semantic intent authority, deciding from meaning rather than fixed phrases.
+Do not run retrieval on unrelated prompts or infer graph from recall intent.
 Prompt hooks attach identity and guidance only; they never retrieve evidence.
-Without attached context, choose the appropriate Runtime operation:
+The full retrieval contract arrives with the session's first prompt as
+`EGREGORE_ACTOR_CONTEXT_V1` (later prompts carry a reminder); follow it.
+When `EGREGORE_ORG_CONTEXT_V1` is attached, reuse its authorized evidence.
+When the full contract is not in your context (a subagent, a missed hook, or
+after a compaction), start with
 
 ```bash
 bash bin/search.sh find "<query>" --kind <kind>
 ```
 
-Choose `filename`, `literal`, or `dates` for canonical file lookups; `keyword`
-for BM25; `semantic` for paraphrases; `hybrid` for combined ranking. No mode
-must run first. Open necessary sources together with `bash bin/search.sh open
-memory/path-a.md memory/path-b.md`. Runtime retains request state; do not write
-JSON operations, episode arguments, or gap explanations for normal retrieval.
-Use `find` for model-led discovery; `query` is a compatibility command. Read
-canonical sources through `search.sh open`, never a raw file-read tool or shell
-read. An adequate excerpt already supports an answer; no extra open is needed.
+and follow `.claude/context/retrieval-investigation.md`.
+Open necessary sources together with `bash bin/search.sh open`; never read
+memory with a raw file tool, `grep` or `ls`. Do not `cd` into the sibling memory repository.
+Never relax the date boundary to manufacture coverage.
 
 Search output is model-internal: show only the retrieval line and receipts —
 never ranked blocks, file/rank/excerpt metadata, or raw JSON.
 
-Do not resolve `memory/` to its sibling repo or start with raw `grep`/`ls`.
-Search attaches no graph by default. Open a source only when its excerpt
-cannot support a necessary claim. For current
-team/person synthesis, retain the requested subject and choose a `recent_days`
-window. Use date filters for a known topic, or a bounded date inventory for
-a recent-work overview. `$activity`, `$dashboard`, and `$project`
-display bounded status surfaces only when named or directly requested as a
-card. Explained syntheses of current organizational work and prior-work
-discovery are Runtime/QMD recall. Do not run retrieval on unrelated prompts or
-infer graph from recall intent.
-
-Do not emit the beat for code search, Git inspection, startup hydration, graph
-writes, ingestion, background sync, maintenance, or internal queries.
-Never name `Egregore Connect` unless a graph read will actually run.
+`$activity`, `$dashboard`, and `$project` display bounded status surfaces only
+when named or directly requested as a card.
+Explained syntheses of current organizational work and prior-work discovery are Runtime/QMD recall.
 
 ---
 
@@ -337,12 +297,15 @@ Never repeat it.
 
 ## Memory
 
-`memory/` is a symlink to the memory repo defined in `egregore.json`. Key directories:
-- `people/` — team directory
-- `handoffs/` — session handoffs + `index.md`
-- `knowledge/decisions/` — org decisions
-- `knowledge/patterns/` — emergent patterns
-- `infrastructure/` — service registry (URLs, names, credential locations)
+`memory/` links to the repo in `egregore.json`:
+- `people/` — team
+- `handoffs/` — handoffs and index
+- `knowledge/decisions/` — decisions
+- `knowledge/patterns/` — patterns
+- `infrastructure/` — services and credential locations
+
+Write memory through its commands, never the files: `$reflect` for decisions, `$handoff` for handoffs.
+
 
 Always use HTTPS for git operations — `github-auth.sh` handles credential storage.
 
@@ -357,9 +320,8 @@ Loom is Claude-specific; skip its preambles and `bin/loom.sh` calls. Use native
 ## Git Workflow
 
 `develop` is the default integration branch. A top-level
-`egregore.json.base_branch` replaces it for instances using another integration
-branch; `base_branch: "main"` is single-branch mode. Users never interact with
-git directly.
+`egregore.json.base_branch` replaces it; `base_branch: "main"` is single-branch
+mode. Users never interact with git directly.
 
 ```
 main ← selected `/release` candidates
@@ -373,10 +335,9 @@ develop ← CL integration (available internally)
 - **On launch**: syncs the configured base branch + memory. Does NOT create a branch.
 - **Branch creation**: required before project changes; read-only work stays put.
 - **Resuming**: rebase onto the configured base branch and continue.
-- **Read-only sessions**: no branch creation based on message count.
 - **`$save`**: pushes the working branch and opens a PR to the configured base. Auto-merges markdown-only PRs.
 - **Memory repo**: stays on main (separate repo, auto-merge).
-- **Never push directly to the configured base, main, or develop.** All changes flow through PRs.
+- **Never push directly to the configured base, main, or develop.** Changes flow through PRs, merged with `bash bin/agent.sh merge <pr>`, never `gh pr merge`; a red check needs a receipt naming each failing job and why.
 
 ### Pull request format (all harnesses)
 
@@ -384,7 +345,7 @@ Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format
 
 ### Commit format (all harnesses)
 
-Every commit follows `.claude/context/commit-format.md`: subject `type(scope): imperative summary` (≤ 72 chars, aim ≤ 50, lowercase, same grammar and type set as PR titles), body wrapped at 72 explaining what and why — never how, and git trailers on agent-authored commits (`Egregore-Session: <id>` from `.egregore-session-id`, plus the harness `Co-Authored-By` line). Background scripts commit as `chore(<subsystem>): …`, but a commit carrying real work derives its type/scope from the diff — the transport never masks the work. Git-generated messages (merges, reverts, autosquash fixups) keep their native form. Wording for commits and PRs follows `.claude/context/git-language.md`.
+Every commit follows `.claude/context/commit-format.md`: subject `type(scope): imperative summary` (≤ 72 chars, aim ≤ 50, lowercase, same grammar and type set as PR titles), body wrapped at 72 explaining what and why — never how, and git trailers on agent-authored commits (`Egregore-Session: <id>` from `bash bin/session-id.sh`, plus the harness `Co-Authored-By` line). Background scripts commit as `chore(<subsystem>): …`, but a commit carrying real work derives its type/scope from the diff — the transport never masks the work. Git-generated messages (merges, reverts, autosquash fixups) keep their native form. Wording for commits and PRs follows `.claude/context/git-language.md`.
 
 ### Managed Repos
 
@@ -392,21 +353,13 @@ Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Ea
 
 ---
 
-## Working Conventions
-
-- For unfamiliar org work, use Observe context; if absent, run `bash bin/search.sh find` with an appropriate lookup kind.
-- Document significant decisions in `memory/knowledge/decisions/`
-- After substantial sessions, log to `memory/handoffs/` and update `index.md`
-
----
-
 ## Command Awareness
 
-Codex reserves leading `/` for built-ins. Invoke Egregore skills with `$name` or natural language ("show activity", "make a handoff"). Every framework workflow uses a generated adapter that names its one maintained body under `.claude/skills/`. Organization-owned skills may also provide full native implementations. `$save` covers committing, pushing, pull requests, and memory sync; users need not manage Git themselves.
+Codex reserves leading `/` for built-ins. Invoke Egregore skills with `$name` or natural language ("show activity", "make a handoff"). Every framework workflow uses a generated adapter that names its one maintained body under `.claude/skills/`. Organization-owned skills may also provide full native implementations.
 
 Invoke commands from user intent — don't wait for the slash. Each command file has a `## When to invoke` section. Load it for the full spec.
 
-**Core loop** — `$activity` `$dashboard` `$handoff` `$wrap` `$save` `$reflect` `$todo`
+**Core loop** — `$activity` `$dashboard` `$handoff` `$wrap` `$save` `$reflect` `$todo` `$records`
 **Knowledge** — `$search` `$deep-reflect` `$archive` `$note` `$add` `$meeting` `$ingest` `$scroll` `$mock` `$audit`
 **Identity** — `$me` (view profile or set display name)
 **Coordination** — `$ask` `$quest` `$issue` `$invite` `$delete-user` `$announce`
@@ -418,16 +371,10 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 
 **Disambiguation:**
 - Knowledge: `$reflect` (share-ready) · `$note` (half-baked) · `$deep-reflect` (deep research over memory — questions AND cross-referencing) · `$archive` (AI patterns) · `$audit` (evidence-mined forensic sweep of the org's own record — any target)
-- Finding things — **the model chooses organizational retrieval through Runtime**.
-  Reuse equivalent evidence and investigate distinct gaps through the same Runtime.
-  Use `bash bin/search.sh find` or `open` and the shared investigation contract. Use Grep/Glob for code and exact errors, not org
-  recall. Do not `cd` into the sibling memory repository.
-- Finding **something you generated** (a scroll, handoff, emissary, decision, any hosted egregore.xyz link): `bash bin/artifacts.sh find <query>`. Every generative surface records into memory — hosted artifacts self-register into `memory/artifacts/` at publish (committed+pushed, findable from any session); handoffs in `memory/handoffs/`, emissaries in `memory/handoffs/outbound/`, decisions/findings/patterns in `memory/knowledge/`. The finder searches all of them by **content, not just name**, ranks title/topic matches above body mentions, tags hits by type (`[document]`/`[handoff]`/`[emissary]`/`[decision]`), and surfaces the shareable URL — grep-first in OSS, search + graph when available. *"bring me the artifact where I laid out our GTM plan"* → this.
+- Finding things — organizational recall through Runtime (Egregore Retrieval Beat); Grep/Glob for code and exact errors.
+- Finding **something you generated** (a scroll, handoff, emissary, decision, any hosted egregore.xyz link): `bash bin/artifacts.sh find <query>` searches every generated record by content, tags its type and returns the shareable URL. *"bring me the artifact where I laid out our GTM plan"* → this.
 - Artifacts with questions: `$scroll` (living paper + embedded harvest, updates in place) · `$view` (static render) · `$harvest` (elicitation, no published face) · `$mock` (pre-build walkthrough of decided design — gauge per stop, verdict copy-back)
-- Explicit bounded status: `$dashboard` (personal) · `$activity` (org-wide) ·
-  `$project` (named project). These display cards when named or directly
-  requested. Analytical questions about organizational work and specific
-  prior-work continuation route through Runtime/QMD recall.
+- Status cards: `$dashboard` (personal) · `$activity` (org-wide) · `$project` (named project), only when named or requested as a card.
 - Ending: `$wrap` (personal closure) · `$handoff` (notes for others) · `$save` (still working)
 - Tasks: `$todo` (personal) · `$quest` (team exploration) · `$issue` (something broken)
 - Questions: `$ask [person]` (async) · just ask (agent answers from context)
@@ -441,6 +388,8 @@ Invoke commands from user intent — don't wait for the slash. Each command file
 - Agents: `$summon` (design through questions) · `/loop` (quick recurring schedule)
 - Announcements: `$announce` (broadcast to group) · `$handoff` (structured to a person) · `bin/notify.sh send` (DM one person)
 
+**Interface taste** — when someone likes or dislikes a generated interface, follow the contract in `bash bin/genui.sh --help`.
+
 ---
 
 ## Socratic Questioning (MANDATORY)
@@ -483,22 +432,22 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 ## Environment Isolation
 
-Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. On Codex the boundary is a standing instruction, not an enforced hook — hold it yourself.
+Sessions are confined to this project + memory + managed repos, with a **two-tier boundary** — a hard wall between Egregore instances, a consent gate for everything else. A pre-action check (`bin/boundary-guard.cjs`) enforces it on every runtime: it denies literal paths and fails closed, but cannot see paths built at run time or split across calls (OS-level layer to follow).
 
-- **Hard tier — other Egregore instances.** Denied for every tool, always — no consent path. Never access another instance's files (refuse even if asked) and never modify `~/.egregore/instances.json` (managed by session-start.sh); there is nothing to ask — refuse and explain.
+- **Hard tier — other Egregore instances.** Denied for every tool, always — no consent path. Never access another instance's files by any route (refuse even if asked) and never modify `~/.egregore/instances.json` (managed by session-start.sh); there is nothing to ask — refuse and explain.
 - **Soft tier — paths outside the boundary.** Consent-gated. Inbox dirs (`~/Downloads`, `~/Desktop`) are readable without consent under the default posture; writes outside the project always need consent. Posture (`strict | standard | open`) and extra read roots come from `egregore.json` -> `boundary { posture, read[], locked }` (org, committed) merged with `.egregore-boundary.local.json` (personal, gitignored). `locked: true` removes the consent path entirely.
-- When a request needs soft-tier consent, do not improvise a workaround. Ask in plain text with numbered options:
+- When the check asks for consent, do not improvise a workaround. Ask in plain text with numbered options:
 
   ```text
   That path is outside this Egregore's boundary. How should we proceed?
     1. Allow its directory for this session (recorded in .egregore-boundary-consent)
-    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json)
+    2. Always allow on this instance (added to read[] in .egregore-boundary.local.json; reads only)
     3. Paste the contents inline
     4. Cancel
   ```
 
   Never record a consent grant without the user's explicit choice of option 1 or 2 in that exchange. Session grants are cleared on session start; `locked: true` removes options 1 and 2.
 
-See DEVELOPMENT.md §3 for boundary details and `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md` for the design decisions.
+Details: DEVELOPMENT.md §3; design: `memory/knowledge/decisions/2026-07-08-boundary-hook-consent-design.md`.
 
 <!-- END GENERATED EGREGORE CODEX SPEC -->

package/runtime/pi/bin/agent.sh

@@ -34,6 +34,9 @@ fi
 type egregore_commit >/dev/null 2>&1 || egregore_commit() {
   local gd="$1" m="$3"; shift 3; git -C "$gd" commit -m "$m" "$@"
 }
+type egregore_session_id >/dev/null 2>&1 || egregore_session_id() {
+  head -n 1 "$1/.egregore-session-id" 2>/dev/null; return 0
+}
 type egregore_pr_skeleton >/dev/null 2>&1 || egregore_pr_skeleton() {
   printf '## What\n%s\n\n## Why\n%s\n\n## Verification\n%s\n\n%s\n' "$1" "$2" "$3" "$4"
 }
@@ -54,7 +57,12 @@ Runtime-neutral commands:
                                    Commit and push current repo + memory changes;
                                    PR body follows .claude/context/pr-format.md
                                    (auto-generated skeleton if not provided);
-                                   new code PRs stay draft until --ready
+                                   new code PRs stay draft until --ready, which
+                                   first runs the checks CI would select here
+  merge <pr> [--receipt FILE] [--dry-run] [--local-receipt FILE]
+                                   Merge a PR into the integration branch through
+                                   the gate: green merges; a red check needs a
+                                   receipt naming it and why (bin/merge-gate.sh)
   autosave [status|on|off|scope|publish|merge]  Personal ambient-save settings + consent
   wrap --topic T --summary TEXT    Write a session wrap to memory/wraps
   handoff --from A --to B --topic T [--intent action|feedback|fyi]
@@ -148,9 +156,13 @@ save_memory() {
   branch="$(memory_branch)"
   [ -z "$branch" ] && branch="main"
   for _try in 1 2 3; do
-    if git -C "$MEMORY_DIR" pull --rebase origin "$branch" --quiet 2>/dev/null \
-       && git -C "$MEMORY_DIR" push origin "$branch" --quiet 2>/dev/null; then
-      return 0
+    if git -C "$MEMORY_DIR" pull --rebase origin "$branch" --quiet 2>/dev/null; then
+      if bash "$SCRIPT_DIR/bin/memory-push.sh" --repository "$MEMORY_DIR" --branch "$branch" >/dev/null 2>&1; then
+        return 0
+      else
+        local push_status=$?
+        case "$push_status" in 75) ;; *) die "memory saved locally; guarded publication is pending review or reconciliation" ;; esac
+      fi
     fi
     sleep 1
   done
@@ -229,6 +241,7 @@ Egregore portable agent protocol
 7. Run `bin/agent.sh search "<query>"` to recall shared memory (decisions, handoffs, knowledge) before answering questions about past work.
 8. Run `bin/agent.sh branch --topic "<what you are working on>"` before code changes when you need a task branch/worktree.
 9. Run `bin/agent.sh save` and `bin/agent.sh wrap` for portable save/wrap flows.
+10. Run `bin/agent.sh merge <pr>` to merge a PR into its integration branch, never `gh pr merge`; a red check needs `--receipt <file>` naming each failing job and why.
 
 This protocol is runtime-neutral. Claude Code may still use .claude hooks and
 skills, while Codex or another agent can call this script directly.
@@ -403,9 +416,188 @@ build_pr_body() {
     "🤖 Saved via bin/agent.sh"
 }
 
+# Inputs of each step the save regenerates, as Git pathspecs. The generators
+# are the authority; re-derive a list when its generator changes. A step's
+# own outputs count as inputs, so a hand edit is regenerated, not committed.
+#   codex-skills  bin/codex-sync-skills.sh: the .codex/skills adapters, from
+#                 .claude/skills frontmatter classified by the skill inventory
+#                 (capability-distribution.json, egregore.json owned_skills)
+#   codex-spec    bin/codex-render-spec.mjs: AGENTS.md and
+#                 .codex/spec-manifest.json, from CLAUDE.md alone
+#   pi-spec       bin/pi-render-spec.mjs: .pi/APPEND_SYSTEM.md, from AGENTS.md
+#   prime-spec    bin/prime-render-spec.mjs: .prime/agent/APPEND_SYSTEM.md,
+#                 from AGENTS.md
+#   bundles       `npm run build:runtime` in packages/create-egregore, chaining
+#     bin/capability-distribution.mjs generate-skill-view and
+#     packages/create-egregore/scripts/build-runtime-bundle.mjs (Codex):
+#       AGENTS.md, .claude/context, .codex, .agents, docs/{credential-entry,spirit-discovery}.md,
+#       egregore_runtime and the bin allowlist; Pi and Prime copy this tree
+#     packages/create-egregore/scripts/build-claude-runtime-bundle.mjs:
+#       CLAUDE.md, .claude/{context,hooks,rules,skills}, the same docs, bin
+#     packages/create-egregore/scripts/build-pi-runtime-bundle.mjs: .pi, bin
+#     packages/create-egregore/scripts/build-prime-runtime-bundle.mjs: .prime, bin
+#     api/scripts/build-connect-runtime-pack.mjs: .claude/skills, .codex/skills
+#     Each reads capability-distribution.json, which selects what ships; the
+#     builders and the package.json script that chains them are inputs too.
+#     A directory stands in for the curated list inside it (bin for the
+#     allowlist): an unrelated change there costs a no-op build of about a
+#     second, while a missing input ships a stale bundle.
+derivation_inputs() {
+  case "$1" in
+    codex-skills) printf '%s\n' .claude/skills .codex/skills capability-distribution.json \
+      egregore.json bin/codex-sync-skills.sh bin/capability-distribution.mjs ;;
+    codex-spec) printf '%s\n' CLAUDE.md AGENTS.md .codex/spec-manifest.json bin/codex-render-spec.mjs ;;
+    pi-spec) printf '%s\n' AGENTS.md .pi/APPEND_SYSTEM.md .pi/spec-manifest.json bin/pi-render-spec.mjs ;;
+    prime-spec) printf '%s\n' AGENTS.md .prime/agent/APPEND_SYSTEM.md \
+      .prime/agent/spec-manifest.json bin/prime-render-spec.mjs ;;
+    bundles) printf '%s\n' \
+      AGENTS.md CLAUDE.md capability-distribution.json docs/credential-entry.md docs/spirit-discovery.md \
+      bin egregore_runtime .agents .codex .pi .prime \
+      .claude/context .claude/hooks .claude/rules .claude/skills \
+      packages/create-egregore/package.json packages/create-egregore/scripts \
+      api/scripts/build-connect-runtime-pack.mjs ;;
+  esac
+}
+
+# What the counted steps write.
+derivation_outputs() {
+  case "$1" in
+    codex-spec) printf '%s\n' AGENTS.md .codex/spec-manifest.json ;;
+    pi-spec) printf '%s\n' .pi/APPEND_SYSTEM.md .pi/spec-manifest.json ;;
+    prime-spec) printf '%s\n' .prime/agent/APPEND_SYSTEM.md .prime/agent/spec-manifest.json ;;
+    bundles) printf '%s\n' packages/create-egregore/runtime api/assets/connect-runtime-pack.json \
+      skill-distribution.json ;;
+  esac
+}
+
+# derivation_due BASE STEP: whether an input of STEP differs in the working
+# tree or, on a task branch, since origin/BASE. Only a task branch's own
+# commits reach its PR: a save from a protected branch starts a new one from
+# origin/BASE. An unavailable comparison counts as a change: regenerating is
+# idempotent, while skipping can commit a stale view.
+derivation_due() {
+  local base="$1" path="" diff=""
+  local -a inputs=()
+  while IFS= read -r path; do inputs+=("$path"); done < <(derivation_inputs "$2")
+  [ -z "$(git -C "$SCRIPT_DIR" status --porcelain --untracked-files=normal -- "${inputs[@]}" 2>/dev/null | head -1)" ] \
+    || return 0
+  case "$(git -C "$SCRIPT_DIR" branch --show-current 2>/dev/null || true)" in
+    dev/*|feature/*|bugfix/*) ;;
+    *) return 1 ;;
+  esac
+  diff="$(git -C "$SCRIPT_DIR" diff --name-only "origin/$base...HEAD" -- "${inputs[@]}" 2>/dev/null)" || return 0
+  [ -n "$diff" ]
+}
+
+# derivation_changes STEP: how many of STEP's outputs differ from HEAD.
+derivation_changes() {
+  local path=""
+  local -a outputs=()
+  while IFS= read -r path; do outputs+=("$path"); done < <(derivation_outputs "$1")
+  git -C "$SCRIPT_DIR" status --porcelain --untracked-files=all -- "${outputs[@]}" | wc -l | tr -d ' '
+}
+
+# run_derivation LABEL COMMAND...: run one step, keeping its output in
+# DERIVED_OUTPUT; a failure shows the last lines and stops the save.
+run_derivation() {
+  local label="$1"
+  shift
+  if ! DERIVED_OUTPUT="$("$@" 2>&1)"; then
+    printf '%s\n' "$DERIVED_OUTPUT" | tail -n 20 >&2
+    die "$label failed (output above); the save stopped before the project commit"
+  fi
+}
+
+# npm_build_runtime NPM NODE_DIR: the build's script chain calls bare node, so
+# the node bin/node-run.sh resolved goes first on PATH, as in
+# bin/artifact-renderer-install.sh.
+npm_build_runtime() {
+  cd "$SCRIPT_DIR/packages/create-egregore" && PATH="$2:$PATH" "$1" run build:runtime
+}
+
+# Regenerate the derived views and runtime bundles before the save commits, so
+# the commit carries them and CI's checks stay a backstop. Steps run in the
+# order their inputs require: the Codex adapters and the three specs feed the
+# bundles, and the Codex render's AGENTS.md feeds the Pi and Prime specs. Each
+# runs only when derivation_due says so and prints one receipt line; a failure
+# stops the save. Sets DERIVED_SUBJECT for a commit of regeneration alone.
+regenerate_derived() {
+  local base="$1" spec="" specs="" rendered="" made="" count="" review="" path="" node_bin="" npm_bin=""
+  local -a inputs=() fresh=()
+
+  if [ ! -f "$SCRIPT_DIR/bin/codex-sync-skills.sh" ]; then
+    echo "codex skills: not applicable"
+  elif ! derivation_due "$base" codex-skills; then
+    echo "codex skills: current"
+  else
+    run_derivation "codex skill sync" bash "$SCRIPT_DIR/bin/codex-sync-skills.sh"
+    count="$(printf '%s\n' "$DERIVED_OUTPUT" | grep -c '^generated adapter: ' || true)"
+    case "$count" in
+      0) echo "codex skills: current" ;;
+      1) echo "codex skills: synced (1 file)"; made="codex adapters" ;;
+      *) echo "codex skills: synced ($count files)"; made="codex adapters" ;;
+    esac
+  fi
+
+  for spec in codex pi prime; do
+    [ -f "$SCRIPT_DIR/bin/$spec-render-spec.mjs" ] || continue
+    specs="$specs $spec"
+    derivation_due "$base" "$spec-spec" || continue
+    run_derivation "$spec spec render" bash "$SCRIPT_DIR/bin/node-run.sh" "$SCRIPT_DIR/bin/$spec-render-spec.mjs"
+    [ "$(derivation_changes "$spec-spec")" = 0 ] || rendered="${rendered:+$rendered, }$spec"
+  done
+  if [ -z "$specs" ]; then
+    echo "specs: not applicable"
+  elif [ -z "$rendered" ]; then
+    echo "specs: current"
+  else
+    echo "specs: rendered ($rendered)"
+    made="${made:+$made, }specs"
+  fi
+  # A hand-written Codex section keeps its text when CLAUDE.md changes under
+  # it; the render refreshes only the source hash that --check used to flag.
+  case "$rendered" in
+    codex*)
+      review="$(git -C "$SCRIPT_DIR" show HEAD:.codex/spec-manifest.json 2>/dev/null \
+        | jq -r --slurpfile now "$SCRIPT_DIR/.codex/spec-manifest.json" '
+            (reduce (.sections // [])[] as $s ({}; .[$s.section] = $s.sourceHash)) as $was
+            | [$now[0].sections[] | select(.action == "replace" and $was[.section] != .sourceHash) | .section]
+            | join(", ")' 2>/dev/null)" || review=""
+      [ -z "$review" ] || echo "specs: review the hand-written Codex sections in bin/codex-render-spec.mjs: $review"
+      ;;
+  esac
+
+  DERIVED_SUBJECT="chore(bundles): regenerate ${made:+$made and }runtime bundles"
+  if ! derivation_due "$base" bundles; then
+    echo "bundles: current"
+    return 0
+  fi
+  # The builders copy only files Git tracks, so new and deleted inputs enter
+  # the index first: a new module ships beside its callers, and a deleted one
+  # leaves the bundle instead of failing the copy.
+  while IFS= read -r path; do inputs+=("$path"); done < <(derivation_inputs bundles)
+  while IFS= read -r -d '' path; do fresh+=("$path"); done \
+    < <(git -C "$SCRIPT_DIR" ls-files -z --others --deleted --exclude-standard -- "${inputs[@]}")
+  if [ "${#fresh[@]}" -gt 0 ]; then
+    git -C "$SCRIPT_DIR" add -A -- "${fresh[@]}" >/dev/null 2>&1 || die "could not stage new bundle inputs"
+  fi
+  node_bin="$(bash "$SCRIPT_DIR/bin/node-run.sh" -p 'process.execPath')" \
+    || die "the bundle rebuild needs Node; install Node 22, then save again"
+  npm_bin="$(command -v npm 2>/dev/null || true)"
+  [ -n "$npm_bin" ] || npm_bin="${node_bin%/*}/npm"
+  [ -x "$npm_bin" ] || die "the bundle rebuild needs npm; install Node with npm, then save again"
+  run_derivation "bundle rebuild" npm_build_runtime "$npm_bin" "${node_bin%/*}"
+  count="$(derivation_changes bundles)" || die "could not read the bundles after the rebuild"
+  case "$count" in
+    0) echo "bundles: current" ;;
+    1) echo "bundles: rebuilt (1 file changed)" ;;
+    *) echo "bundles: rebuilt ($count files changed)" ;;
+  esac
+}
+
 cmd_save() {
   local message="" topic="" no_pr=0 branch base pushed="false" committed="false" pr_url="" existing_pr="" pr_number="" merged="false" pr_body="" pr_body_file=""
-  local readiness="" pr_draft="" changed_paths="" non_code="" use_pr=0
+  local readiness="" pr_draft="" changed_paths="" non_code="" use_pr=0 commit_message="" tree_was_clean=0 checks_failed=0
   local -a create_args
 
   while [ $# -gt 0 ]; do
@@ -450,12 +642,26 @@ cmd_save() {
     echo "memory: synced"
   fi
 
+  commit_message="$message"
+  # Installed instances carry the derived views and bundles but not the
+  # builders; /update regenerates their views.
+  if [ -f "$SCRIPT_DIR/packages/create-egregore/package.json" ]; then
+    [ -n "$(git -C "$SCRIPT_DIR" status --porcelain --untracked-files=normal 2>/dev/null | head -1)" ] \
+      || tree_was_clean=1
+    regenerate_derived "$base"
+    # On a clean tree the regeneration makes the only changes, so they commit
+    # under their own subject; the caller's message describes committed work.
+    [ "$tree_was_clean" = "0" ] || commit_message="$DERIVED_SUBJECT"
+  else
+    printf '%s\n' "codex skills: not applicable" "specs: not applicable" "bundles: not applicable"
+  fi
+
   branch="$(git -C "$SCRIPT_DIR" branch --show-current 2>/dev/null || echo "")"
   if [ -n "$(git -C "$SCRIPT_DIR" status --porcelain 2>/dev/null | head -1)" ]; then
     branch="$(ensure_working_branch "$topic")"
     git -C "$SCRIPT_DIR" add -A >/dev/null 2>&1 || die "git add failed"
     if ! git -C "$SCRIPT_DIR" diff --cached --quiet 2>/dev/null; then
-      egregore_commit "$SCRIPT_DIR" "$SCRIPT_DIR" "$message" --quiet || die "git commit failed"
+      egregore_commit "$SCRIPT_DIR" "$SCRIPT_DIR" "$commit_message" --quiet || die "git commit failed"
       committed="true"
     fi
   fi
@@ -486,6 +692,18 @@ cmd_save() {
       if [ -n "$pr_url" ]; then
         pr_number="$(printf '%s' "$existing_pr" | jq -r '.[0].number')"
         pr_draft="$(printf '%s' "$existing_pr" | jq -r '.[0].isDraft')"
+      fi
+      # A PR goes ready only after the checks CI would select pass here. On a
+      # failure the work is still pushed, as a draft, so GitHub never spends
+      # a run on what this machine already saw fail. Installed instances do
+      # not ship the runner.
+      if [ "$readiness" = "--ready" ] && [ -f "$SCRIPT_DIR/bin/ci-local.py" ]; then
+        if ! python3 "$SCRIPT_DIR/bin/ci-local.py" --base "$base"; then
+          checks_failed=1
+          readiness="--draft"
+        fi
+      fi
+      if [ -n "$pr_url" ]; then
         # Convert before push: a synchronize event must already see the draft.
         if [ "$readiness" = "--draft" ] && [ "$pr_draft" = "false" ]; then
           (cd "$SCRIPT_DIR" && gh pr ready "$pr_number" --undo) \
@@ -545,6 +763,10 @@ cmd_save() {
   [ -n "$pr_url" ] && echo "pr: $pr_url"
   [ -n "$pr_draft" ] && echo "pr-draft: $pr_draft"
   [ "$merged" = "true" ] && echo "merge: non-coding, merged to $base"
+  if [ "$checks_failed" = "1" ]; then
+    echo "local checks failed: the work is pushed and the PR stays a draft; fix the checks above, then save again with --ready" >&2
+    return 1
+  fi
   return 0
 }
 
@@ -608,7 +830,7 @@ cmd_wrap() {
   local capture_args=(--mode personal)
   tmpd="$(mktemp -d -t egregore-agent-wrap-XXXXXX)"
   trap 'rm -rf "$tmpd"' RETURN
-  session_id="$(cat "$SCRIPT_DIR/.egregore-session-id" 2>/dev/null || true)"
+  session_id="$(egregore_session_id "$SCRIPT_DIR")"
   branch="$(git -C "$SCRIPT_DIR" branch --show-current 2>/dev/null || true)"
   [ "$no_push" = "1" ] && capture_args+=(--no-push)
 
@@ -884,7 +1106,9 @@ case "${1:-}" in
   people) shift; cmd_people "$@" ;;
   branch) shift; cmd_branch "$@" ;;
   save) shift; cmd_save "$@" ;;
+  merge) shift; exec bash "$SCRIPT_DIR/bin/merge-gate.sh" "$@" ;;
   autosave) shift; bash "$SCRIPT_DIR/bin/autosave.sh" "$@" ;;
+  records) shift; bash "$SCRIPT_DIR/bin/records.sh" "$@" ;;
   wrap) shift; cmd_wrap "$@" ;;
   wrap-card) shift; render_wrap_card "$@" ;;
   handoff) shift; cmd_handoff "$@" ;;