create-egregore 0.20.0 → 0.20.1

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'
@@ -360,8 +369,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 +391,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 +404,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 +427,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,26 +179,17 @@ 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
@@ -208,14 +199,20 @@ integration branch.
 
 ### 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,7 +259,7 @@ 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.
+Memory, managed-repo, and runtime-state writes bypass the project guard — if one triggers it, correct the target/context instead of asking for consent.
 
 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.
 
@@ -272,7 +267,7 @@ If this Codex build does not support hooks, follow the same discipline as a stan
 
 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 +275,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 +322,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
     }

package/runtime/codex/bin/handoff-pr-backfill.sh

@@ -77,7 +77,7 @@ if [ -d "$MEMORY_DIR" ]; then
   (
     cd "$MEMORY_DIR" || exit 0
     git add -A >/dev/null 2>&1
-    git commit -m "Backfill PR numbers for handoff: $TOPIC" >/dev/null 2>&1 || exit 0
+    git commit -m "chore(handoff): backfill PR numbers for $TOPIC" >/dev/null 2>&1 || exit 0
     git pull --rebase origin main --quiet >/dev/null 2>&1
     git push origin main --quiet >/dev/null 2>&1
   ) || true

package/runtime/codex/bin/handoff-run.sh

@@ -36,6 +36,11 @@ set -euo pipefail
 #   1 on unrecoverable failure (file write, memory push, bad args).
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+# 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" "$@"
+}
 CONFIG="$SCRIPT_DIR/egregore.json"
 
 if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
@@ -326,12 +331,12 @@ PID_ARTIFACTS=$!
     git add "$REL_FILE" handoffs/index.md >/dev/null 2>&1
 
     if [ -n "$RECIPIENT" ]; then
-      MSG_COMMIT="Handoff: ${TOPIC} (to ${RECIPIENT})"
+      MSG_COMMIT="chore(handoff): record ${TOPIC} (to ${RECIPIENT})"
     else
-      MSG_COMMIT="Handoff: ${TOPIC}"
+      MSG_COMMIT="chore(handoff): record ${TOPIC}"
     fi
 
-    git commit -m "$MSG_COMMIT" >/dev/null 2>&1 || true
+    egregore_commit . "$SCRIPT_DIR" "$MSG_COMMIT" >/dev/null 2>&1 || true
 
     STASHED=0
     if [ -n "$(git status --porcelain 2>/dev/null)" ]; then

package/runtime/codex/bin/handoff-save-egregore.sh

@@ -47,19 +47,16 @@ done
 
 case "$KIND" in
   autosave)
-    MSG_PREFIX="Auto-save"
+    MSG_PREFIX="chore(autosave): save"
     PR_WHAT="Save session content captured by the opted-in autosave workflow."
     PR_WHY="This preserves unattended non-coding work without requiring an explicit /save."
     ;;
   *)
-    MSG_PREFIX="Handoff"
+    MSG_PREFIX="chore(handoff): record"
     PR_WHAT="Save core-repository session work captured when the handoff was created."
     PR_WHY="The handoff records shared context immediately; this companion PR keeps the originating checkout's work from remaining only local."
     ;;
 esac
-PR_BODY=$(printf '## What\n\n- %s\n\n## Why\n\n%s Topic: `%s`.\n\n## Verification\n\nNot verified — background %s save; review code or configuration changes before merging.\n\n🤖 Saved via `bin/handoff-save-egregore.sh`\n' \
-  "$PR_WHAT" "$PR_WHY" "$TOPIC" "$KIND")
-
 [ -n "$AUTHOR" ] || { echo "handoff-save-egregore: missing author" >&2; exit 1; }
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
@@ -88,6 +85,21 @@ BASE_REF="origin/$BASE_BRANCH"
 . "$SCRIPT_DIR/bin/lib/git-safe.sh" 2>/dev/null || true
 type git_add_guarded >/dev/null 2>&1 || git_add_guarded() { git add -A 2>/dev/null || true; }
 
+# 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"
+}
+PR_BODY=$(egregore_pr_skeleton \
+  "- $PR_WHAT" \
+  "$PR_WHY Topic: \`$TOPIC\`." \
+  "Not verified — background $KIND save; review code or configuration changes before merging." \
+  "🤖 Saved via \`bin/handoff-save-egregore.sh\`")
+
 # Shared non-coding classifier (auto-merge policy lives in one place).
 # shellcheck source=bin/lib/noncode.sh
 . "$SCRIPT_DIR/bin/lib/noncode.sh" 2>/dev/null || true
@@ -131,7 +143,7 @@ fi
 # --- Commit whatever is uncommitted --------------------------------------
 if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
   git_add_guarded
-  git commit -m "${MSG_PREFIX}: ${TOPIC}" --quiet 2>/dev/null || true
+  egregore_commit . "$REPO_DIR" "${MSG_PREFIX} ${TOPIC}" --quiet 2>/dev/null || true
 fi
 
 # --- Rebase onto the configured base, fall back to merge on conflicts ----
@@ -182,7 +194,7 @@ else
   PR_URL=$(gh pr create \
     --base "$BASE_BRANCH" \
     --head "$CURRENT_BRANCH" \
-    --title "${MSG_PREFIX}: ${TOPIC}" \
+    --title "${MSG_PREFIX} ${TOPIC}" \
     --body "$PR_BODY" \
     2>/dev/null || echo "")
   PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$' || echo "")

package/runtime/codex/bin/ingest.py

@@ -154,6 +154,36 @@ def chunks(text: str, limit: int = 7000) -> list[str]:
     return result
 
 
+# Catalogue columns that carry provenance, by what they mean rather than by
+# what any one organisation calls them. A profile's `map` already renames its
+# own columns to these, so no further configuration is needed.
+CATALOGUE_URL_FIELDS = ("url", "source_url", "link")
+CATALOGUE_INSTITUTION_FIELDS = ("institution", "publisher", "source_type", "source")
+
+
+def catalogue_provenance(catalogued: dict) -> tuple:
+    """The URL and institution a catalogue records for a document.
+
+    The resolver has always accepted these and ranks both above a filename,
+    because a filename is what someone happened to save a file as. Ingest
+    passed only the filename, so the stronger evidence sitting in the row it
+    had just read went unused.
+
+    Measured on a real archive that was not a marginal loss. Seventy articles
+    downloaded from two journal indexes were saved under bare article titles,
+    carrying no publisher token to match. The profile had rules for both
+    indexes and the catalogue named the index for every one of them, and still
+    nothing matched — the one input that could have identified them was the one
+    input never passed.
+    """
+    if not catalogued:
+        return "", ""
+    url = next((str(catalogued[f]) for f in CATALOGUE_URL_FIELDS if catalogued.get(f)), "")
+    institution = next(
+        (str(catalogued[f]) for f in CATALOGUE_INSTITUTION_FIELDS if catalogued.get(f)), "")
+    return url, institution
+
+
 def find_publisher_profile() -> Path | None:
     """Where this instance's publisher profile is, if it has one.
 
@@ -267,6 +297,17 @@ def add_path(args: argparse.Namespace) -> dict:
     )
     repair_map = text_repair.load_mapping(profile or {})
     ingested = unchanged = metadata_updated = skipped = pruned = 0
+    # How often progress is written. The manifest used to be saved once, after
+    # every file, so an interrupted run lost everything it had extracted — on a
+    # 921-document folder that was two and a half hours of OCR with nothing to
+    # show. Documents already on disk were re-extracted because nothing recorded
+    # them. Writing periodically means an interruption costs at most this many.
+    checkpoint_every = int(os.environ.get("EGREGORE_INGEST_CHECKPOINT", "25") or 0)
+    since_checkpoint = 0
+    # Read before the loop rather than after it, so a checkpoint writes the real
+    # deletion records instead of dropping them. Pruning still happens later; a
+    # mid-run save simply carries forward what the previous run recorded.
+    tombstones = existing_manifest.get("tombstones", [])
     errors: list[dict] = []
     seen_paths: set[str] = set()
 
@@ -390,7 +431,10 @@ def add_path(args: argparse.Namespace) -> dict:
             provenance["confidence"] = "high"
 
         if profile:
-            resolved = source_profile.resolve(profile, filename=relative)
+            catalogue_url, catalogue_institution = catalogue_provenance(catalogued)
+            resolved = source_profile.resolve(
+                profile, url=catalogue_url, institution=catalogue_institution,
+                filename=relative)
             if resolved.publisher_class or resolved.notes:
                 inferred = resolved.as_dict()
                 # Keep the inference visible even when the catalogue answered,
@@ -438,12 +482,18 @@ def add_path(args: argparse.Namespace) -> dict:
             "status": "unverified",
             "ingested_at": now,
         }
+        since_checkpoint += 1
+        if checkpoint_every and since_checkpoint >= checkpoint_every:
+            # A crash between the document write and this one costs re-extraction
+            # of at most `checkpoint_every` files, never the whole run.
+            write_manifest(directory, source_id, org, args, boundaries, base, now,
+                           previous, tombstones, errors)
+            since_checkpoint = 0
         if existing and existing.get("content_hash") == content_hash:
             metadata_updated += 1
         else:
             ingested += 1
 
-    tombstones = existing_manifest.get("tombstones", [])
     if args.prune:
         if not input_path.is_dir():
             raise ValueError("--prune requires a directory snapshot")
@@ -465,11 +515,23 @@ def add_path(args: argparse.Namespace) -> dict:
     # Current documents always win over historical deletion records.
     tombstones = [row for row in tombstones if row["id"] not in previous]
 
+    write_manifest(directory, source_id, org, args, boundaries, base, now,
+                   previous, tombstones, errors)
+    return {"org": org, "source": source_id, "ingested": ingested, "unchanged": unchanged, "metadata_updated": metadata_updated, "skipped": skipped, "pruned": pruned, "documents": len(previous), "metadata_root": str(directory), "data_root": str(docs_dir)}
+
+
+def write_manifest(directory, source_id, org, args, boundaries, base, now,
+                   previous, tombstones, errors) -> None:
+    """Persist progress. Called periodically during a run and once at the end.
+
+    One writer for both so a checkpoint and a completed run cannot record the
+    corpus differently.
+    """
     source_record = {
         "id": source_id,
         "org": org,
-        "name": args.name or source_id,
-        "kind": args.kind,
+        "name": getattr(args, "name", None) or source_id,
+        "kind": getattr(args, "kind", None),
         "boundaries": boundaries,
         "root_hint": base.name,
         "updated_at": now,
@@ -486,7 +548,6 @@ def add_path(args: argparse.Namespace) -> dict:
             "errors": errors,
         },
     )
-    return {"org": org, "source": source_id, "ingested": ingested, "unchanged": unchanged, "metadata_updated": metadata_updated, "skipped": skipped, "pruned": pruned, "documents": len(previous), "metadata_root": str(directory), "data_root": str(docs_dir)}
 
 
 def cmd_add(args: argparse.Namespace) -> int:
@@ -494,6 +555,191 @@ def cmd_add(args: argparse.Namespace) -> int:
     return 0
 
 
+def rewrite_frontmatter(path: Path, updates: dict) -> bool:
+    """Replace named frontmatter fields in place, leaving the text untouched.
+
+    A document's placement lives in two files — the manifest record and this
+    document's own frontmatter — and a reader may consult either. Updating one
+    and not the other produces a corpus that disagrees with itself, which is
+    worse than the stale value it replaced.
+
+    Only the named lines are rewritten. The body is never reparsed, so nothing
+    that survived extraction can be lost by a maintenance pass.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    lines = text.split("\n")
+    if not lines or lines[0].strip() != "---":
+        return False
+    try:
+        close = next(i for i in range(1, len(lines)) if lines[i].strip() == "---")
+    except StopIteration:
+        return False
+    remaining = dict(updates)
+    for i in range(1, close):
+        key = lines[i].split(":", 1)[0].strip()
+        if key in remaining:
+            lines[i] = f"{key}: {json.dumps(remaining.pop(key), ensure_ascii=False)}"
+    # A field the original write omitted is appended rather than dropped, so a
+    # document ingested before a field existed still gains it.
+    for key, value in remaining.items():
+        lines.insert(close, f"{key}: {json.dumps(value, ensure_ascii=False)}")
+        close += 1
+    atomic_text(path, "\n".join(lines))
+    return True
+
+
+def reresolve_source(args: argparse.Namespace) -> dict:
+    """Re-derive placement for documents already ingested.
+
+    Placement is written once, at ingest, and never revisited. That is right
+    for content — the text of a document does not change because a rule did —
+    but wrong for the rules themselves. Correcting a publisher profile changed
+    nothing about the corpus it governs: `add` skips on the content hash and
+    returns before it ever consults the profile, so it reported every document
+    unchanged while the corrected rule went unapplied. The only way to apply a
+    fix was to re-extract thousands of documents, redoing OCR to recompute a
+    field that depends on nothing but the filename.
+
+    So this re-runs the resolver alone. No file is reopened, no text is
+    re-extracted; the stored path is all the resolver ever needed.
+
+    Evidence precedence is the same as at ingest, and is the reason this is
+    safe to run at any time: a value the operator stated, or one the
+    organisation's own catalogue recorded, is never overwritten by an
+    inference. Only a placement this resolver derived — or the absence of one —
+    is open to revision.
+    """
+    config = load_config()
+    source_id = slug(args.source)
+    directory = source_dir(source_id)
+    manifest = load_manifest(directory)
+    records = manifest.get("documents") or []
+    if not records:
+        return {"source": source_id, "error": "no manifest, or no documents in it",
+                "metadata_root": str(directory)}
+
+    profile = publisher_profile()
+    if profile is None:
+        return {"source": source_id,
+                "error": "no publisher-profile.json found — nothing to resolve against"}
+    key = source_profile.boundary_key(profile)
+    if not key:
+        return {"source": source_id, "error": "profile declares no boundary key"}
+
+    docs_dir = data_root() / "sources" / source_id / "documents"
+    placed = rezoned = identified = unchanged = protected = missing = 0
+    changes: list = []
+
+    for record in records:
+        relative = record.get("source_path")
+        if not relative:
+            unchanged += 1
+            continue
+        boundaries = dict(record.get("boundaries") or {})
+        provenance = dict(record.get("provenance") or {})
+        catalogued = provenance.get("from_catalogue") or {}
+
+        # The same evidence the original ingest had, re-read from the record so
+        # a document identified only by its catalogue row resolves here too.
+        catalogue_url, catalogue_institution = catalogue_provenance(catalogued)
+        resolved = source_profile.resolve(
+            profile, url=catalogue_url, institution=catalogue_institution,
+            filename=relative)
+
+        # Placement and identification are decided separately. A document can
+        # become identifiable — a journal index naming its publisher — without
+        # that saying anything about which region it applies to, and reporting
+        # only the placement would call that document unchanged when the thing
+        # that decides how far to trust it has just been settled.
+        current = boundaries.get(key)
+        # Anything the operator stated or the catalogue recorded outranks an
+        # inference and is left exactly as it is.
+        derived_here = (provenance.get("derived") is True
+                        and provenance.get("applied_boundary") == key)
+        zone_open = not ((current and not derived_here) or catalogued.get(key))
+        zone_changes = bool(zone_open and resolved.zone and resolved.zone != current)
+
+        # A tier the catalogue stated is likewise not ours to revise.
+        class_open = not catalogued.get("tier")
+        class_changes = bool(
+            class_open and resolved.publisher_class
+            and (resolved.publisher_class != provenance.get("publisher_class")
+                 or resolved.tier != provenance.get("tier")))
+
+        if not zone_changes and not class_changes:
+            if not zone_open and not class_open:
+                protected += 1
+            elif current and not zone_open:
+                protected += 1
+            else:
+                unchanged += 1
+            continue
+
+        # The fresh resolution replaces the recorded inference whenever either
+        # half moved. Refreshing only on a class change once left a re-zoned
+        # document carrying the confidence and notes of the resolution it no
+        # longer had — a record that reported an inferred national zone with
+        # the confidence of a precise one.
+        updated_provenance = dict(provenance)
+        updated_provenance.update(resolved.as_dict())
+        if class_changes:
+            identified += 1
+        if catalogued:
+            updated_provenance["from_catalogue"] = catalogued
+        if zone_changes:
+            updated_provenance["applied_boundary"] = key
+            updated_provenance["derived"] = True
+            boundaries[key] = resolved.zone
+            if current:
+                rezoned += 1
+            else:
+                placed += 1
+
+        changes.append({"id": record["id"], "source_path": relative,
+                        "zone": {"from": current, "to": boundaries.get(key)},
+                        "class": {"from": provenance.get("publisher_class"),
+                                  "to": updated_provenance.get("publisher_class")},
+                        "matched_by": resolved.matched_by})
+
+        if args.dry_run:
+            continue
+        record["boundaries"] = boundaries
+        record["provenance"] = updated_provenance
+        file_path = record.get("file_path")
+        target = (data_root() / file_path) if file_path else (docs_dir / f"{record['id']}.md")
+        if not rewrite_frontmatter(target, {"boundaries": boundaries,
+                                            "provenance": updated_provenance}):
+            missing += 1
+
+    if not args.dry_run and (placed or rezoned or identified):
+        manifest["documents"] = sorted(records, key=lambda d: d["id"])
+        atomic_json(directory / "manifest.json", manifest)
+
+    return {
+        "org": slug(config.get("slug") or "egregore"),
+        "source": source_id,
+        "dry_run": bool(args.dry_run),
+        "documents": len(records),
+        "placed": placed,
+        "rezoned": rezoned,
+        "identified": identified,
+        "unchanged": unchanged,
+        "protected": protected,
+        "frontmatter_not_found": missing,
+        "examples": changes[: max(0, args.examples)],
+        "metadata_root": str(directory),
+    }
+
+
+def cmd_reresolve(args: argparse.Namespace) -> int:
+    result = reresolve_source(args)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 1 if result.get("error") else 0
+
+
 def selection_relative_path(value: object) -> str:
     if not isinstance(value, str) or not value or "\x00" in value or "\\" in value:
         raise ValueError("selection contains an invalid relative path")
@@ -719,6 +965,15 @@ def parser() -> argparse.ArgumentParser:
     add.add_argument("--boundary", action="append", default=[])
     add.add_argument("--prune", action="store_true", help="tombstone files absent from this authoritative directory snapshot")
     add.set_defaults(func=cmd_add)
+    reresolve = sub.add_parser(
+        "reresolve",
+        help="re-derive placement from the current profile, without re-reading any document")
+    reresolve.add_argument("--source", required=True, help="source id to re-resolve")
+    reresolve.add_argument("--dry-run", action="store_true",
+                           help="report what would change and write nothing")
+    reresolve.add_argument("--examples", type=int, default=10,
+                           help="how many changed documents to list (default 10)")
+    reresolve.set_defaults(func=cmd_reresolve)
     add_selection = sub.add_parser("add-selection")
     add_selection.add_argument("manifest")
     add_selection.set_defaults(func=cmd_add_selection)