create-egregore 0.20.0 → 0.20.2

package/runtime/codex/.codex/skills/telegram-connect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telegram-connect
-description: 'Fallback Codex adapter for the Egregore telegram-connect workflow.'
+description: 'Set up Telegram as a notification center for your Egregore — creates the group, links the bot, and stores the chat ID. Use for /telegram-connect, ''connect telegram'', or ''set up telegram notifications''.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/codex/.codex/skills/telemetry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: telemetry
-description: 'Fallback Codex adapter for the Egregore telemetry workflow.'
+description: 'Manage your own telemetry settings — check status, opt in/out, view or clear the buffered events. Use for /telemetry, ''turn off telemetry'', or ''what data do you collect''.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/codex/.codex/skills/test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test
-description: 'Fallback Codex adapter for the Egregore test workflow.'
+description: 'Validate changes before /save — static analysis plus live Cypher validation against the graph, rendered as a pass/fail gate. Use for /test or ''test my changes''.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/codex/.codex/skills/tutorial/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tutorial
-description: 'Fallback Codex adapter for the Egregore tutorial workflow.'
+description: 'Interactive walkthrough of Egregore''s core loop — /activity, /reflect, and /quest or /add — with adaptive questions and real artifacts. Use for /tutorial or ''walk me through Egregore''.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/codex/.codex/skills/update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update
-description: 'Fallback Codex adapter for the Egregore update workflow.'
+description: 'Update local Egregore environment — sync the framework from upstream, run post-update migrations, and pull repos. Use for /update or when framework behavior seems broken or missing.'
 ---
 
 <!-- generated-by: bin/codex-sync-skills.sh -->

package/runtime/codex/.codex/spec-manifest.json

@@ -11,7 +11,7 @@
     {
       "section": "Identity & Upstream",
       "action": "keep",
-      "sourceHash": "ddcbc0083aff",
+      "sourceHash": "86a2c62ce498",
       "note": "Kept; /update, /contribute, /save tokens rendered as $skill tokens."
     },
     {
@@ -35,8 +35,8 @@
     {
       "section": "After Greeting — BRANCH ON FIRST RESPONSE",
       "action": "replace",
-      "sourceHash": "d28a5c162ab4",
-      "note": "EnterWorktree -> bin/agent.sh branch with git checkout fallback; AskUserQuestion -> numbered options in plain text; branch-guard mapped to .codex/hooks/branch-guard.js with instruction fallback; plan-mode note dropped (no plan mode on Codex); /branch + /onboarding -> skill tokens. Handoff claiming and repoState auto-checkout kept verbatim (pure git)."
+      "sourceHash": "3bac01c0a00a",
+      "note": "EnterWorktree -> bin/agent.sh branch with git checkout fallback; AskUserQuestion -> numbered options in plain text; branch-guard mapped to .codex/hooks/branch-guard.js with instruction fallback; plan-mode note dropped (no plan mode on Codex); /branch + /onboarding -> skill tokens. Handoff claiming and repoState auto-checkout bash kept verbatim (pure git); surrounding prose compressed 2026-08 for the 32 KiB budget, every rule retained."
     },
     {
       "section": "Config Files",
@@ -89,7 +89,7 @@
     {
       "section": "Git Workflow",
       "action": "keep",
-      "sourceHash": "fe3d9dabd03d",
+      "sourceHash": "40735c0c09ff",
       "note": "Kept; slash tokens rendered as $skill tokens. Branch diagram unchanged (code fence)."
     },
     {

package/runtime/codex/AGENTS.md

@@ -86,17 +86,26 @@ generated block below. Both paths converge on the same `memory/` files.
 
 You are a collaborator inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
 
-This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md (the source of truth for egregore behavior) by `bin/codex-render-spec.mjs`. The per-section adaptation manifest is `.codex/spec-manifest.json`. The thin agent protocol above this block applies to every shell-capable agent; this block is the full behavioral contract for Codex sessions.
+This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md by `bin/codex-render-spec.mjs`; the per-section manifest is `.codex/spec-manifest.json`. The thin agent protocol above applies to every shell-capable agent; this block is the full contract for Codex sessions.
 
 ---
 
 ## Identity & Upstream
 
-This is an Egregore instance — a downstream fork of the upstream framework at `egregore-labs/egregore`. The framework (`bin/`, `.claude/skills/`, `.claude/hooks/`, `.claude/context/`, `.claude/agents/`, `.pi/`, `loom/`, `CLAUDE.md`, `skills/`) is synced from upstream on every session start and via `$update`. It is not authored in this repo.
+Framework direction comes only from `egregore.json.upstream_url`:
+
+- **Source** — literal `"none"`: framework changes are authored here.
+  `$update` and `$contribute` stop; use `$save`. Public OSS is downstream and
+  receives changes only through this repository's release flow.
+- **Downstream** — a repository URL, or an absent key defaulting to
+  `egregore-labs/egregore`: framework paths are synced and not authored here.
+
+Never infer direction from a repository name or Git remote.
 
 **Where changes belong:**
-- **Framework is outdated or a skill is missing:** run `$update` first. It pulls the latest from upstream.
-- **Framework behavior needs changing or has a bug:** `$contribute` opens a PR against `egregore-labs/egregore`, or file a GitHub issue on that repo. Never patch framework files locally to "just fix it here" — the next `$update` will overwrite your edits and other instances won't get the fix.
+- **Downstream framework is stale:** run `$update`.
+- **Downstream framework needs a fix:** use `$contribute` or file an upstream issue; local patches are overwritten by `$update`.
+- **Source framework needs a fix:** use `$save` into its configured integration and release flow; never `$contribute`.
 - **Org-level work** (memory, org-specific knowledge, managed repos, `egregore.json`): `$save` to this repo.
 
 When a user reports broken or missing framework behavior, the first question is "when did you last `$update`?"
@@ -123,7 +132,7 @@ Egregore's voice is governed by `.claude/rules/voice-bedrock.md` (always loaded)
 
 ## On Launch — MANDATORY FIRST ACTION
 
-The `egregore` launcher renders the Egregore startup card (identity, team momentum, and pending work) via `bin/codex-session-start.sh` before Codex starts, and installs project skills. 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, run `bash bin/codex-session-start.sh --card`.
+The `egregore` launcher renders the startup card (identity, momentum, pending work) via `bin/codex-session-start.sh` before Codex starts and installs project skills. Do not rerun or 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. Re-show with `bash bin/codex-session-start.sh --card`.
 
 ---
 
@@ -131,37 +140,34 @@ The `egregore` launcher renders the Egregore startup card (identity, team moment
 
 **Mandatory behavioral rule.** When the user describes work, your **first action** — before reading files, exploring code, or anything else — is to get onto a working branch:
 
-The integration branch is `develop` by default. When top-level
-`egregore.json.base_branch` is set, that configured branch replaces
-`develop` as the branch point, rebase target, PR base, and protected
-integration branch.
+The integration branch is `develop` unless top-level `egregore.json.base_branch` sets another; the configured branch is then the branch point, rebase target, PR base, and protected branch everywhere below.
 
 1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
 2. Run `bin/agent.sh branch --topic "<topic>"` — it resolves the configured base and creates a work branch from `origin/{base}` in a task worktree (`dev/{author}/{slug}`, or `feature/{slug}` / `bugfix/{slug}` when the topic reads as a feature or fix). Continue all file work from the printed path.
-3. Give a value-first workspace receipt. Do not lead with Git terminology:
-
-   `Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.`
-
-   Then expose the implementation as secondary detail:
-
-   `Workspace: {branch} (worktree).`
+3. Give a value-first workspace receipt — do not lead with Git terminology: `Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.` Then, as secondary detail: `Workspace: {branch} (worktree).`
 
 **Fallback:** If `bin/agent.sh branch` fails, resolve `{base}` with
 `_get_base_branch`, then use
-`git checkout -b dev/{author}/{slug} origin/{base}`.
+`git checkout --no-track -b dev/{author}/{slug} origin/{base}`.
 
 4. Update graph (fire-and-forget): `bash bin/graph-op.sh set-topic "$(cat .egregore-session-id 2>/dev/null)" "topic from slug" "dev/author/slug" 2>/dev/null &`
 
 ### Starting-work UX contract
 
-Before execution begins, make Egregore's useful structure legible without turning every task start into a tutorial:
+Sequence: **intent → safe workspace → relevant context → consequential assumptions → execution**. Make Egregore's structure legible without turning task starts into a tutorial; keep technical identifiers secondary to user value.
 
-- **Workspace** — use the value-first receipt above for a newly created workspace or topic pivot. If already on the appropriate working branch, do not repeat it.
-- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat and then add one compact result receipt: `↳ Context restored: {decision, handoff, or prior work} · {source/date}`. Never claim context was restored when retrieval found nothing useful.
-- **Assumptions** — surface only consequential assumptions that could change the implementation. Use `Assumption: {assumption} — based on {evidence}.` Add a correction path when cheap; do not narrate obvious operational choices.
-- **Transition** — once workspace, context, and assumptions are settled, state the outcome you are starting toward in one short sentence and begin.
+- **Workspace** — the value-first receipt above, only for a new workspace or topic pivot; do not repeat it on the same branch.
+- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat plus one compact receipt: `↳ Context restored: {decision, handoff, or prior work} · {source/date}`. Never claim context was restored when retrieval found nothing useful.
+- **Assumptions** — surface only consequential ones: `Assumption: {assumption} — based on {evidence}.` Add a correction path when cheap; do not narrate obvious operational choices.
+- **Transition** — state the outcome you are starting toward in one short sentence and begin.
 
-The intended sequence is: **intent → safe workspace → relevant context → consequential assumptions → execution**. Keep technical identifiers available but subordinate them to user value.
+### Returning-work UX contract
+
+When the user continues the current branch's work or asks to resume — sequence: **continuation intent → prior workspace → restored context → open threads → resumed execution**:
+
+- Do not create a new workspace for the same topic. After confirming relevance, say: `I found your previous work on **{topic}** and restored its workspace and context.` Show `Workspace: {branch} (worktree).` secondarily.
+- Retrieve relevant decisions, handoffs, or prior work; keep the Retrieval Beat and `↳ Context restored:` receipt. Never claim context was restored from a branch name alone.
+- Name only unresolved items that could change the next move, state the next outcome briefly, and continue without replaying setup.
 
 ### Handoff claiming
 
@@ -170,7 +176,7 @@ If `addressed_to_user` handoffs exist and the user is picking one up, create the
 bash bin/graph-op.sh claim-handoff "$SESSION_ID" "$HANDOFF_SESSION_ID" 2>/dev/null &
 ```
 
-**Auto-checkout repos from handoff**: After claiming, check the `addressed_rich` context for `repoState`. If the handoff includes repo state (non-empty `repoState` array), check out the handoff's branches in each managed repo:
+**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)"
@@ -183,21 +189,19 @@ if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
 fi
 ```
 
-Report results: `✓ Checked out {branch} in {repo1}, {repo2}`. If a branch no longer exists (PR was merged): `◐ {repo}: PR #{N} merged — on {base}`. If `repoState` is absent or empty, skip auto-checkout silently.
+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.
 
-**Exceptions** — skip branching when:
-- The user explicitly created or named a branch themselves
-- Already on a working branch AND the user's intent continues the current branch's topic
+**Exceptions** — skip branching when the user explicitly created or named a branch themselves, or the intent continues the current working branch's topic.
 
-**Topic pivot while on a working branch:** If the user describes work **unrelated** to the current branch's topic, treat it as a new topic and create a new branch (`bin/agent.sh branch --topic "<new topic>"`). Do NOT mix unrelated work on one branch.
+**Topic pivot:** work **unrelated** to the current branch's topic gets a new branch (`bin/agent.sh branch --topic "<new topic>"`). Do NOT mix unrelated work on one branch.
 
 If still on the configured base branch after two messages, create a branch immediately from whatever context you have.
 
 ### Branch-guard protocol
 
-The `.codex/hooks/branch-guard.js` PreToolUse hook (enabled by the launcher via `--enable hooks`) protects project writes on the configured base branch as well as `develop`/`main`/`master`. Its block message is operational guidance, not a reason to interrupt the user with routine Git choices:
+The `.codex/hooks/branch-guard.js` PreToolUse hook (launcher `--enable hooks`) protects project writes on the configured base plus `develop`/`main`/`master`. Its block message is operational guidance — do not interrupt the user with routine Git choices:
 
-- **Topic is clear** (the user said "fix X", "add Y feature") → run `bin/agent.sh branch --topic "<topic>"` automatically, continue in the printed worktree, and say one short sentence so the branch change is visible. Do not ask the user to approve routine branching.
+- **Topic is clear** → run `bin/agent.sh branch --topic "<topic>"` automatically, continue in the printed worktree, and say one short sentence so the change is visible — never ask approval for routine branching.
 - **Topic is genuinely ambiguous** → ask only for the topic, using compact numbered options:
 
   ```text
@@ -210,9 +214,11 @@ The `.codex/hooks/branch-guard.js` PreToolUse hook (enabled by the launcher via
   Wait for the reply, then branch.
 - **The user explicitly requested the protected branch** → that request is consent. Record it with `echo '{branch}' > .egregore-branch-consent`, then retry. Never create the marker merely to silence the hook.
 
-Memory, managed-repo, and runtime-state writes should bypass the project guard. If one triggers it, correct the operation target/context instead of asking for protected-branch consent.
+If this Codex build does not support hooks, keep the same rule.
 
-If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on the configured base, develop, main, or master.
+**History:** Do not merge, cherry-pick, or rebase another task merely to read
+it; use `gh pr view/diff`, `git show`, or a temporary worktree. Integrate
+only for dependencies. Deletion needs no rewrite unless purging secrets.
 
 ### Onboarding exception
 
@@ -348,7 +354,7 @@ Always use HTTPS for git operations — `github-auth.sh` handles credential stor
 
 ## Loom Routing
 
-Loom routes commands across model tiers on the Claude Code runtime (`loom/routes.json` + `bin/loom.sh` + a model-pinned executor subagent). Codex has no subagent delegation — every command runs inline in the current session. Ignore "Loom routing" preambles if you encounter them in a skill spec, and skip `bin/loom.sh` calls; `loom/` and `.claude/agents/` are framework files synced for the Claude runtime.
+Loom routes commands across model tiers on the Claude Code runtime (`loom/routes.json` + `bin/loom.sh` + a model-pinned executor subagent). Codex has no subagent delegation — commands run inline. Ignore "Loom routing" preambles in skill specs and skip `bin/loom.sh` calls; `loom/` and `.claude/agents/` are Claude-runtime framework files.
 
 ---
 
@@ -360,11 +366,14 @@ branch; `base_branch: "main"` is single-branch mode. Users never interact with
 git directly.
 
 ```
-main ← stable (/release)
-  develop ← integration (PRs land here)
-    dev/{author}/{topic-slug} | feature/{slug} | bugfix/{slug}
+main ← selected `/release` candidates
+develop ← CL integration (available internally)
+  dev/{author}/{topic-slug} | feature/{slug} | bugfix/{slug}
 ```
 
+- **Develop is not release**: merged PRs stay inside CL.
+- **`$release` is selective**: the Release Desk queues exact PR SHAs into a candidate from main. Never merge all of develop.
+- **OSS is separate**: `$sync-public` reviews delivery after private main.
 - **On launch**: syncs the configured base branch + memory. Does NOT create a branch.
 - **Branch creation**: MANDATORY on first work-related message (see above).
 - **Resuming**: rebase onto the configured base branch and continue.
@@ -377,6 +386,10 @@ main ← stable (/release)
 
 Every PR body follows `.claude/context/pr-format.md`, enforced by the `pr-format` CI check regardless of which harness opened it: `## What` (1–4 bullets) + `## Why` (1–3 sentences) always; `## Verification` when the diff touches non-markdown files (how it was checked, or an honest `Not verified — <reason>`); `## Risk`/`## Links` when real; title `type(scope): imperative summary` (advisory). **Never create a PR with an empty body or `--fill`** — write the body and pass it explicitly (`gh pr create --body`, or `bin/agent.sh save --pr-body` for shell agents; the bridge auto-generates a compliant skeleton only as a last resort).
 
+### 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`.
+
 ### Managed Repos
 
 Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Each entry can be a string or `{"name": "...", "description": "..."}`. Match user intent to the right repo using `description`. Same branching strategy. Use `git -C` with absolute paths — never `cd` into repos. `$save` scans all managed repos for uncommitted changes.
@@ -393,7 +406,7 @@ Repos in `egregore.json` → `repos[]` are cloned as siblings (`../{repo}/`). Ea
 
 ## Command Awareness
 
-Codex reserves leading `/` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching `$name` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: `$activity`, `$handoff`, `$wrap`, `$announce`, `$harvest`, `$the-spiral`, `$dashboard`, `$deep-reflect`, `$quest`, `$invite`, `$ask`, `$save`, `$view`, and `$scroll`. Every other workflow has a generated adapter skill of the same name. `$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.
+Codex reserves leading `/` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching `$name` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: `$activity`, `$handoff`, `$wrap`, `$announce`, `$harvest`, `$the-spiral`, `$dashboard`, `$deep-reflect`, `$quest`, `$invite`, `$ask`, `$save`, `$view`, `$scroll`; every other workflow has a generated adapter of the same name. `$save` is the user-facing abstraction for committing, pushing, opening or reusing PRs, and syncing memory — never make users manage git by hand.
 
 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.
 
@@ -470,7 +483,7 @@ Egregore runs in one of two configurations, set by `mode` in `egregore.json`. De
 
 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.
 
-- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify `~/.egregore/instances.json` (managed by session-start.sh). When a request points at another instance's files 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 (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:
 

package/runtime/codex/bin/agent.sh

@@ -23,6 +23,15 @@ if [ -f "$SCRIPT_DIR/bin/lib/config.sh" ]; then
   # shellcheck source=bin/lib/config.sh
   source "$SCRIPT_DIR/bin/lib/config.sh"
 fi
+# Shared commit/PR message mechanics (trailers + skeleton body shape).
+# shellcheck source=bin/lib/git-message.sh
+. "$SCRIPT_DIR/bin/lib/git-message.sh" 2>/dev/null || true
+type egregore_commit >/dev/null 2>&1 || egregore_commit() {
+  local gd="$1" m="$3"; shift 3; git -C "$gd" commit -m "$m" "$@"
+}
+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"
+}
 
 usage() {
   cat <<'EOF'
@@ -178,6 +187,15 @@ base_ref() {
   fi
 }
 
+clear_base_upstream() {
+  local repo="$1" branch="$2" base="$3" upstream=""
+  case "$branch" in dev/*|feature/*|bugfix/*) ;; *) return 0 ;; esac
+  upstream="$(git -C "$repo" rev-parse --abbrev-ref "${branch}@{upstream}" 2>/dev/null || true)"
+  if [ "$upstream" = "$base" ]; then
+    git -C "$repo" branch --unset-upstream "$branch" >/dev/null 2>&1 || true
+  fi
+}
+
 cmd_protocol() {
   cat <<'EOF'
 Egregore portable agent protocol
@@ -297,8 +315,9 @@ cmd_branch() {
     if git -C "$SCRIPT_DIR" show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
       git -C "$SCRIPT_DIR" checkout "$branch" --quiet
     else
-      git -C "$SCRIPT_DIR" checkout -b "$branch" "$base" --quiet
+      git -C "$SCRIPT_DIR" checkout --no-track -b "$branch" "$base" --quiet
     fi
+    clear_base_upstream "$SCRIPT_DIR" "$branch" "$base"
     egregore_link_shared_state "$SCRIPT_DIR" "$MAIN_PROJECT_DIR" >/dev/null 2>/dev/null || true
     echo "branch: $branch"
     echo "worktree: $SCRIPT_DIR"
@@ -314,8 +333,9 @@ cmd_branch() {
   fi
 
   if ! git -C "$MAIN_PROJECT_DIR" show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
-    git -C "$MAIN_PROJECT_DIR" branch "$branch" "$base" >/dev/null 2>&1 || die "failed to create branch $branch"
+    git -C "$MAIN_PROJECT_DIR" branch --no-track "$branch" "$base" >/dev/null 2>&1 || die "failed to create branch $branch"
   fi
+  clear_base_upstream "$MAIN_PROJECT_DIR" "$branch" "$base"
 
   wt_path="$MAIN_PROJECT_DIR/.claude/worktrees/$slug"
   if [ -e "$wt_path" ]; then
@@ -347,8 +367,9 @@ ensure_working_branch() {
   if git -C "$SCRIPT_DIR" show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
     git -C "$SCRIPT_DIR" checkout "$branch" --quiet || die "failed to checkout $branch"
   else
-    git -C "$SCRIPT_DIR" checkout -b "$branch" "$base" --quiet || die "failed to create $branch"
+    git -C "$SCRIPT_DIR" checkout --no-track -b "$branch" "$base" --quiet || die "failed to create $branch"
   fi
+  clear_base_upstream "$SCRIPT_DIR" "$branch" "$base"
   echo "$branch"
 }
 
@@ -360,8 +381,11 @@ build_pr_body() {
   commits="$(git -C "$SCRIPT_DIR" log --pretty='- %s' "origin/$base..HEAD" 2>/dev/null | head -8)"
   [ -n "$commits" ] || commits="- (commit list unavailable — see the Files tab)"
   stat="$(git -C "$SCRIPT_DIR" diff --shortstat "origin/$base...HEAD" 2>/dev/null | sed 's/^ *//')"
-  printf '## What\n%s\n\n## Why\nShell-agent session save — topic: %s. Body auto-generated by bin/agent.sh; pass --pr-body for a hand-written description.\n\n## Verification\nNot verified — auto-generated skeleton; review the diff before merging.%s\n\n🤖 Saved via bin/agent.sh\n' \
-    "$commits" "$topic" "${stat:+ ($stat)}"
+  egregore_pr_skeleton \
+    "$commits" \
+    "Shell-agent session save — topic: $topic. Body auto-generated by bin/agent.sh; pass --pr-body for a hand-written description." \
+    "Not verified — auto-generated skeleton; review the diff before merging.${stat:+ ($stat)}" \
+    "🤖 Saved via bin/agent.sh"
 }
 
 cmd_save() {
@@ -379,7 +403,7 @@ cmd_save() {
   done
 
   [ -n "$topic" ] || topic="portable save"
-  [ -n "$message" ] || message="Save: $topic"
+  [ -n "$message" ] || message="chore(save): $topic"
   base="$(resolve_base_branch)" || die "save stopped before Git changes"
 
   if [ -d "$MEMORY_DIR" ]; then
@@ -392,7 +416,7 @@ cmd_save() {
     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
-      git -C "$SCRIPT_DIR" commit -m "$message" --quiet || die "git commit failed"
+      egregore_commit "$SCRIPT_DIR" "$SCRIPT_DIR" "$message" --quiet || die "git commit failed"
       committed="true"
     fi
   fi
@@ -415,7 +439,7 @@ cmd_save() {
         pr_body="$(cat "$pr_body_file")"
       fi
       [ -n "$pr_body" ] || pr_body="$(build_pr_body "$topic")"
-      pr_url="$(gh pr create --base "$base" --head "$branch" --title "$message" --body "$pr_body" 2>/dev/null || true)"
+      pr_url="$(gh pr create --base "$base" --head "$branch" --title "${message%%$'\n'*}" --body "$pr_body" 2>/dev/null || true)"
     fi
   fi
 

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

@@ -179,43 +179,40 @@ function transformTokens(body) {
 
 const INTRO_BODY = `You are a collaborator inside Egregore — a shared intelligence layer for organizations using AI coding agents. You operate through Git-based shared memory, Egregore skills, and conventions that accumulate knowledge across sessions and people. You are not a tool. You are a participant.
 
-This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md (the source of truth for egregore behavior) by \`bin/codex-render-spec.mjs\`. The per-section adaptation manifest is \`.codex/spec-manifest.json\`. The thin agent protocol above this block applies to every shell-capable agent; this block is the full behavioral contract for Codex sessions.`;
+This block is the Codex-native Egregore behavioral spec, rendered from CLAUDE.md by \`bin/codex-render-spec.mjs\`; the per-section manifest is \`.codex/spec-manifest.json\`. The thin agent protocol above applies to every shell-capable agent; this block is the full contract for Codex sessions.`;
 
-const ON_LAUNCH_BODY = `The \`egregore\` launcher renders the Egregore startup card (identity, team momentum, and pending work) via \`bin/codex-session-start.sh\` before Codex starts, and installs project skills. 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, run \`bash bin/codex-session-start.sh --card\`.`;
+const ON_LAUNCH_BODY = `The \`egregore\` launcher renders the startup card (identity, momentum, pending work) via \`bin/codex-session-start.sh\` before Codex starts and installs project skills. Do not rerun or 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. Re-show with \`bash bin/codex-session-start.sh --card\`.`;
 
 const AFTER_GREETING_BODY = `**Mandatory behavioral rule.** When the user describes work, your **first action** — before reading files, exploring code, or anything else — is to get onto a working branch:
 
-The integration branch is \`develop\` by default. When top-level
-\`egregore.json.base_branch\` is set, that configured branch replaces
-\`develop\` as the branch point, rebase target, PR base, and protected
-integration branch.
+The integration branch is \`develop\` unless top-level \`egregore.json.base_branch\` sets another; the configured branch is then the branch point, rebase target, PR base, and protected branch everywhere below.
 
 1. Derive a topic slug from what the user said (kebab-case, 2–4 words)
 2. Run \`bin/agent.sh branch --topic "<topic>"\` — it resolves the configured base and creates a work branch from \`origin/{base}\` in a task worktree (\`dev/{author}/{slug}\`, or \`feature/{slug}\` / \`bugfix/{slug}\` when the topic reads as a feature or fix). Continue all file work from the printed path.
-3. Give a value-first workspace receipt. Do not lead with Git terminology:
-
-   \`Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.\`
-
-   Then expose the implementation as secondary detail:
-
-   \`Workspace: {branch} (worktree).\`
+3. Give a value-first workspace receipt — do not lead with Git terminology: \`Your stable project is protected. I’m working in a separate workspace for **{topic}**, where changes stay isolated, reviewable, and reversible.\` Then, as secondary detail: \`Workspace: {branch} (worktree).\`
 
 **Fallback:** If \`bin/agent.sh branch\` fails, resolve \`{base}\` with
 \`_get_base_branch\`, then use
-\`git checkout -b dev/{author}/{slug} origin/{base}\`.
+\`git checkout --no-track -b dev/{author}/{slug} origin/{base}\`.
 
 4. Update graph (fire-and-forget): \`bash bin/graph-op.sh set-topic "$(cat .egregore-session-id 2>/dev/null)" "topic from slug" "dev/author/slug" 2>/dev/null &\`
 
 ### Starting-work UX contract
 
-Before execution begins, make Egregore's useful structure legible without turning every task start into a tutorial:
+Sequence: **intent → safe workspace → relevant context → consequential assumptions → execution**. Make Egregore's structure legible without turning task starts into a tutorial; keep technical identifiers secondary to user value.
+
+- **Workspace** — the value-first receipt above, only for a new workspace or topic pivot; do not repeat it on the same branch.
+- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat plus one compact receipt: \`↳ Context restored: {decision, handoff, or prior work} · {source/date}\`. Never claim context was restored when retrieval found nothing useful.
+- **Assumptions** — surface only consequential ones: \`Assumption: {assumption} — based on {evidence}.\` Add a correction path when cheap; do not narrate obvious operational choices.
+- **Transition** — state the outcome you are starting toward in one short sentence and begin.
+
+### Returning-work UX contract
 
-- **Workspace** — use the value-first receipt above for a newly created workspace or topic pivot. If already on the appropriate working branch, do not repeat it.
-- **Context** — when organizational retrieval materially informs the work, keep the required Egregore Retrieval Beat and then add one compact result receipt: \`↳ Context restored: {decision, handoff, or prior work} · {source/date}\`. Never claim context was restored when retrieval found nothing useful.
-- **Assumptions** — surface only consequential assumptions that could change the implementation. Use \`Assumption: {assumption} — based on {evidence}.\` Add a correction path when cheap; do not narrate obvious operational choices.
-- **Transition** — once workspace, context, and assumptions are settled, state the outcome you are starting toward in one short sentence and begin.
+When the user continues the current branch's work or asks to resume — sequence: **continuation intent → prior workspace → restored context → open threads → resumed execution**:
 
-The intended sequence is: **intent → safe workspace → relevant context → consequential assumptions → execution**. Keep technical identifiers available but subordinate them to user value.
+- Do not create a new workspace for the same topic. After confirming relevance, say: \`I found your previous work on **{topic}** and restored its workspace and context.\` Show \`Workspace: {branch} (worktree).\` secondarily.
+- Retrieve relevant decisions, handoffs, or prior work; keep the Retrieval Beat and \`↳ Context restored:\` receipt. Never claim context was restored from a branch name alone.
+- Name only unresolved items that could change the next move, state the next outcome briefly, and continue without replaying setup.
 
 ### Handoff claiming
 
@@ -224,7 +221,7 @@ If \`addressed_to_user\` handoffs exist and the user is picking one up, create t
 bash bin/graph-op.sh claim-handoff "$SESSION_ID" "$HANDOFF_SESSION_ID" 2>/dev/null &
 \`\`\`
 
-**Auto-checkout repos from handoff**: After claiming, check the \`addressed_rich\` context for \`repoState\`. If the handoff includes repo state (non-empty \`repoState\` array), check out the handoff's branches in each managed repo:
+**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)"
@@ -237,21 +234,19 @@ if [ -d "$REPO_DIR/.git" ] || [ -f "$REPO_DIR/.git" ]; then
 fi
 \`\`\`
 
-Report results: \`✓ Checked out {branch} in {repo1}, {repo2}\`. If a branch no longer exists (PR was merged): \`◐ {repo}: PR #{N} merged — on {base}\`. If \`repoState\` is absent or empty, skip auto-checkout silently.
+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.
 
-**Exceptions** — skip branching when:
-- The user explicitly created or named a branch themselves
-- Already on a working branch AND the user's intent continues the current branch's topic
+**Exceptions** — skip branching when the user explicitly created or named a branch themselves, or the intent continues the current working branch's topic.
 
-**Topic pivot while on a working branch:** If the user describes work **unrelated** to the current branch's topic, treat it as a new topic and create a new branch (\`bin/agent.sh branch --topic "<new topic>"\`). Do NOT mix unrelated work on one branch.
+**Topic pivot:** work **unrelated** to the current branch's topic gets a new branch (\`bin/agent.sh branch --topic "<new topic>"\`). Do NOT mix unrelated work on one branch.
 
 If still on the configured base branch after two messages, create a branch immediately from whatever context you have.
 
 ### Branch-guard protocol
 
-The \`.codex/hooks/branch-guard.js\` PreToolUse hook (enabled by the launcher via \`--enable hooks\`) protects project writes on the configured base branch as well as \`develop\`/\`main\`/\`master\`. Its block message is operational guidance, not a reason to interrupt the user with routine Git choices:
+The \`.codex/hooks/branch-guard.js\` PreToolUse hook (launcher \`--enable hooks\`) protects project writes on the configured base plus \`develop\`/\`main\`/\`master\`. Its block message is operational guidance — do not interrupt the user with routine Git choices:
 
-- **Topic is clear** (the user said "fix X", "add Y feature") → run \`bin/agent.sh branch --topic "<topic>"\` automatically, continue in the printed worktree, and say one short sentence so the branch change is visible. Do not ask the user to approve routine branching.
+- **Topic is clear** → run \`bin/agent.sh branch --topic "<topic>"\` automatically, continue in the printed worktree, and say one short sentence so the change is visible — never ask approval for routine branching.
 - **Topic is genuinely ambiguous** → ask only for the topic, using compact numbered options:
 
   \`\`\`text
@@ -264,15 +259,17 @@ The \`.codex/hooks/branch-guard.js\` PreToolUse hook (enabled by the launcher vi
   Wait for the reply, then branch.
 - **The user explicitly requested the protected branch** → that request is consent. Record it with \`echo '{branch}' > .egregore-branch-consent\`, then retry. Never create the marker merely to silence the hook.
 
-Memory, managed-repo, and runtime-state writes should bypass the project guard. If one triggers it, correct the operation target/context instead of asking for protected-branch consent.
+If this Codex build does not support hooks, keep the same rule.
 
-If this Codex build does not support hooks, follow the same discipline as a standing instruction: never write or commit on the configured base, develop, main, or master.
+**History:** Do not merge, cherry-pick, or rebase another task merely to read
+it; use \`gh pr view/diff\`, \`git show\`, or a temporary worktree. Integrate
+only for dependencies. Deletion needs no rewrite unless purging secrets.
 
 ### Onboarding exception
 
 If the startup card output contains \`onboarding_needed\`, invoke the \`$onboarding\` skill instead of greeting.`;
 
-const COMMAND_AWARENESS_PREPEND = `Codex reserves leading \`/\` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching \`$name\` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: \`$activity\`, \`$handoff\`, \`$wrap\`, \`$announce\`, \`$harvest\`, \`$the-spiral\`, \`$dashboard\`, \`$deep-reflect\`, \`$quest\`, \`$invite\`, \`$ask\`, \`$save\`, \`$view\`, and \`$scroll\`. Every other workflow has a generated adapter skill of the same name. \`$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.`;
+const COMMAND_AWARENESS_PREPEND = `Codex reserves leading \`/\` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching \`$name\` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: \`$activity\`, \`$handoff\`, \`$wrap\`, \`$announce\`, \`$harvest\`, \`$the-spiral\`, \`$dashboard\`, \`$deep-reflect\`, \`$quest\`, \`$invite\`, \`$ask\`, \`$save\`, \`$view\`, \`$scroll\`; every other workflow has a generated adapter of the same name. \`$save\` is the user-facing abstraction for committing, pushing, opening or reusing PRs, and syncing memory — never make users manage git by hand.`;
 
 const SOCRATIC_BODY = `**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
 
@@ -280,11 +277,11 @@ Codex has no structured question tool — render each batch as compact numbered
 
 **Rules:** Max 4 questions per batch. When choices aren't mutually exclusive, say "pick any that apply".`;
 
-const LOOM_ROUTING_BODY = `Loom routes commands across model tiers on the Claude Code runtime (\`loom/routes.json\` + \`bin/loom.sh\` + a model-pinned executor subagent). Codex has no subagent delegation — every command runs inline in the current session. Ignore "Loom routing" preambles if you encounter them in a skill spec, and skip \`bin/loom.sh\` calls; \`loom/\` and \`.claude/agents/\` are framework files synced for the Claude runtime.`;
+const LOOM_ROUTING_BODY = `Loom routes commands across model tiers on the Claude Code runtime (\`loom/routes.json\` + \`bin/loom.sh\` + a model-pinned executor subagent). Codex has no subagent delegation — commands run inline. Ignore "Loom routing" preambles in skill specs and skip \`bin/loom.sh\` calls; \`loom/\` and \`.claude/agents/\` are Claude-runtime framework files.`;
 
 const ISOLATION_BODY = `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.
 
-- **Hard tier — other Egregore instances.** Denied for every tool, always. There is no consent path. Never access another instance's files — refuse even if asked. Never modify \`~/.egregore/instances.json\` (managed by session-start.sh). When a request points at another instance's files 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 (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:
 
@@ -327,7 +324,7 @@ const RULES = {
   'After Greeting — BRANCH ON FIRST RESPONSE': {
     action: 'replace',
     body: AFTER_GREETING_BODY,
-    note: 'EnterWorktree -> bin/agent.sh branch with git checkout fallback; AskUserQuestion -> numbered options in plain text; branch-guard mapped to .codex/hooks/branch-guard.js with instruction fallback; plan-mode note dropped (no plan mode on Codex); /branch + /onboarding -> skill tokens. Handoff claiming and repoState auto-checkout kept verbatim (pure git).',
+    note: 'EnterWorktree -> bin/agent.sh branch with git checkout fallback; AskUserQuestion -> numbered options in plain text; branch-guard mapped to .codex/hooks/branch-guard.js with instruction fallback; plan-mode note dropped (no plan mode on Codex); /branch + /onboarding -> skill tokens. Handoff claiming and repoState auto-checkout bash kept verbatim (pure git); surrounding prose compressed 2026-08 for the 32 KiB budget, every rule retained.',
   },
   'Config Files': { action: 'keep', note: 'Kept verbatim — shell facts, runtime-neutral.' },
   'Knowledge Graph': { action: 'keep', note: 'Kept verbatim — bin/graph.sh is runtime-neutral.' },

package/runtime/codex/bin/codex-sync-skills.sh

@@ -101,7 +101,12 @@ skill_description() {
     in_fm && $0 == "---" { exit }
     in_fm && /^description:/ {
       sub(/^description:[[:space:]]*/, "")
-      gsub(/^"|"$/, "")
+      # Block scalars (description: >) keep the text on continuation lines we
+      # do not read. Emit nothing so the caller falls back, which the skill-v1
+      # contract check reports, rather than publishing the indicator itself.
+      if ($0 ~ /^[>|][-+]?[[:space:]]*$/) { exit }
+      if ($0 ~ /^".*"$/) { gsub(/^"|"$/, "") }
+      else if ($0 ~ /^\047.*\047$/) { gsub(/^\047|\047$/, ""); gsub(/\047\047/, "\047") }
       print
       exit
     }