create-egregore 0.20.0 → 0.20.2

package/runtime/pi/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)

package/runtime/pi/bin/lib/git-message.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# git-message.sh — shared commit/PR message mechanics, sourced by composers.
+# Spec: .claude/context/commit-format.md + .claude/context/pr-format.md.
+#
+# Provides:
+#   egregore_session_trailer <hub_dir>
+#       Print "Egregore-Session: <id>" when <hub_dir>/.egregore-session-id
+#       exists; print nothing otherwise. Never fails.
+#   egregore_commit <git_dir> <hub_dir> <message> [git-commit flags…]
+#       git -C <git_dir> commit with the session trailer appended as the
+#       final paragraph (a valid git trailer block) when an id exists.
+#   egregore_pr_skeleton <what> <why> <verification> <footer>
+#       The one source of the skeleton PR body shape.
+
+egregore_session_trailer() {
+  local sid
+  sid="$(cat "${1:-.}/.egregore-session-id" 2>/dev/null || true)"
+  [ -n "$sid" ] && printf 'Egregore-Session: %s' "$sid"
+  return 0
+}
+
+egregore_commit() {
+  local git_dir="$1" hub_dir="$2" msg="$3"
+  shift 3
+  local trailer
+  trailer="$(egregore_session_trailer "$hub_dir")"
+  if [ -n "$trailer" ]; then
+    git -C "$git_dir" commit -m "$msg" -m "$trailer" "$@"
+  else
+    git -C "$git_dir" commit -m "$msg" "$@"
+  fi
+}
+
+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"
+}

package/runtime/pi/bin/lib/git-sync.sh

@@ -32,6 +32,22 @@ if [ -z "${BASE_BRANCH:-}" ]; then
   fi
 fi
 
+# Migrate task branches created by older Egregore versions. `git branch
+# <task> origin/<base>` implicitly made the task branch track the protected
+# integration branch, so a bare push could target it when push.default was
+# `upstream`. Task branches remain unpublished until the explicit save/push
+# flow creates their same-name remote and sets that as upstream.
+_CURRENT_TASK_BRANCH="$(git branch --show-current 2>/dev/null || true)"
+case "$_CURRENT_TASK_BRANCH" in
+  dev/*|feature/*|bugfix/*)
+    _CURRENT_TASK_UPSTREAM="$(git rev-parse --abbrev-ref '@{upstream}' 2>/dev/null || true)"
+    if [ "$_CURRENT_TASK_UPSTREAM" = "origin/$BASE_BRANCH" ]; then
+      git branch --unset-upstream "$_CURRENT_TASK_BRANCH" >/dev/null 2>&1 || true
+    fi
+    ;;
+esac
+unset _CURRENT_TASK_BRANCH _CURRENT_TASK_UPSTREAM
+
 # --- Ensure pull.rebase is set (prevents "divergent branches" errors) ---
 git config pull.rebase true 2>/dev/null || true
 
@@ -185,7 +201,7 @@ _apply_framework_update() {
     FRAMEWORK_UPDATED_COUNT=$(printf '%s\n' "$_changed" | grep -c . || echo 0)
     FRAMEWORK_UPDATED_FILES=$(printf '%s\n' "$_changed" | awk '{print $NF}' | head -3 | tr '\n' ' ')
     git add bin/ .claude/ loom/ CLAUDE.md skills/ 2>/dev/null
-    EGREGORE_FRAMEWORK_UPDATE=1 git commit -m "Auto-update Egregore framework" --quiet 2>/dev/null || true
+    EGREGORE_FRAMEWORK_UPDATE=1 git commit -m "chore(sync): update framework from upstream" --quiet 2>/dev/null || true
     FRAMEWORK_UPDATED="true"
   fi
 }
@@ -214,6 +230,14 @@ fi
 # Named setup_develop for continuity; it operates on $BASE_BRANCH, which is
 # "develop" by default and whatever egregore.json's base_branch says otherwise.
 setup_develop() {
+  # Detached HEAD (CI merge-ref checkouts, bisects): never create or switch
+  # branches here — `git checkout -b $BASE_BRANCH origin/$BASE_BRANCH` would
+  # silently replace the checked-out tree with the base branch. This is how
+  # CI jobs that invoke session-start machinery ended up testing develop
+  # instead of the PR under test. Syncing means updating the base-branch ref,
+  # not claiming HEAD; on a detached HEAD there is nothing safe to do.
+  [ -n "$(git branch --show-current 2>/dev/null)" ] || return 0
+
   # Ensure the base branch exists locally
   if ! git show-ref --verify --quiet "refs/heads/$BASE_BRANCH" 2>/dev/null; then
     if git show-ref --verify --quiet "refs/remotes/origin/$BASE_BRANCH" 2>/dev/null; then
@@ -267,7 +291,7 @@ setup_develop() {
       # Save uncommitted work so nothing is lost (guarded: never auto-commit
       # stray submodule pointers from sibling repos in the checkout)
       git_add_guarded
-      git commit -m "Auto-save: uncommitted work from $CURRENT_BRANCH" --quiet 2>/dev/null || true
+      git commit -m "chore(autosave): save uncommitted work from $CURRENT_BRANCH" --quiet 2>/dev/null || true
       SAVED_BRANCH="$CURRENT_BRANCH"
     fi
 

package/runtime/pi/bin/lib/greeting.sh

@@ -13,7 +13,7 @@
 #   - Telemetry emit
 #   - First session welcome
 #
-# Inputs:  SCRIPT_DIR, STATE_FILE, CONFIG, CTX_DIR, BRANCH, COMMITS_AHEAD,
+# Inputs:  SCRIPT_DIR, STATE_FILE, CONFIG, CTX_DIR, BRANCH, BASE_BRANCH, COMMITS_AHEAD,
 #          AUTHOR, LOCAL_MODE, MEMORY_SYNCED, SAVED_BRANCH,
 #          HEALTH_*, FRAMEWORK_VERSION, TIME_OF_DAY, EGREGORE_SESSION_ID,
 #          FIRST_SESSION, DISPLAY_NAME_STATE, DASHBOARD_URL
@@ -515,5 +515,5 @@ else
   echo ""
   echo "IMPORTANT: Display the above greeting to the user exactly as-is (preserve the ASCII art formatting and ornamented status) on their first message. Then ask: What are you working on?"
   echo ""
-  echo "BRANCH RULE: When the user responds with what they're working on, your FIRST action is to create a working branch: git fetch origin develop --quiet && git checkout -b dev/{author}/{topic-slug} origin/develop. Do this BEFORE any other work. Derive the topic slug from their description. If they ask a pure question with no work intent, skip branching."
+  echo "BRANCH RULE: When the user responds with what they're working on, your FIRST action is to create a working branch: git fetch origin $BASE_BRANCH --quiet && git checkout --no-track -b dev/{author}/{topic-slug} origin/$BASE_BRANCH. Do this BEFORE any other work. Derive the topic slug from their description. If they ask a pure question with no work intent, skip branching."
 fi

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

@@ -40,24 +40,57 @@ function replaceSection(markdown, heading, body) {
   return `${markdown.slice(0, start)}${marker}\n\n${body}${markdown.slice(end)}`;
 }
 
+// Keep an inherited section and put runtime-specific framing in front of it.
+// Command Awareness is the case that matters: the canonical category rows and
+// disambiguation map live in CLAUDE.md, and a full replace here silently
+// shipped a truncated copy that drifted for months. The Codex spec opens the
+// section with its own skills-not-slash-commands paragraph, which is wrong for
+// a runtime that does have slash commands, so that one paragraph is dropped.
+function prependToSection(markdown, heading, body, dropLeadParagraphStartingWith) {
+  const marker = `## ${heading}`;
+  const start = markdown.indexOf(marker);
+  if (start < 0) throw new Error(`missing section in AGENTS.md: ${heading}`);
+  const rest = markdown.slice(start + marker.length);
+  const boundary = rest.search(/\n\n---\n\n## /);
+  const end = boundary < 0 ? markdown.length : start + marker.length + boundary;
+  let inherited = markdown.slice(start + marker.length, end).trim();
+  if (dropLeadParagraphStartingWith) {
+    if (!inherited.startsWith(dropLeadParagraphStartingWith)) {
+      throw new Error(`pi/prime-render-spec: "${heading}" no longer opens with "${dropLeadParagraphStartingWith}" — the Codex wording moved; update this adaptation`);
+    }
+    inherited = inherited.slice(inherited.indexOf("\n\n") + 2).trim();
+  }
+  return replaceSection(markdown, heading, `${body}\n\n${inherited}`);
+}
+
+const CODEX_COMMAND_LEAD = "Codex reserves leading";
+
 function adapt(sourceSpec) {
-  let text = sourceSpec
-    .replaceAll("Egregore on Codex", "Egregore on Pi")
-    .replaceAll("Codex-native", "Pi-native")
-    .replaceAll("Codex sessions", "Pi sessions")
-    .replaceAll("On Codex", "On Pi")
-    .replaceAll("from Codex", "from Pi")
-    .replaceAll("inside Codex", "inside Pi")
-    .replaceAll("Codex has no", "Pi has no built-in")
-    .replaceAll("normal sandboxed Codex shell", "the Pi shell")
-    .replaceAll("Codex graph network access", "Pi graph network access")
-    .replaceAll("structured Codex question tooling", "Pi UI question tooling")
-    .replaceAll("structured Codex", "structured Pi")
-    .replaceAll("bin/codex-session-start.sh", "bin/pi-session-start.sh")
-    .replaceAll(".codex/hooks/branch-guard.js", ".pi/extensions/egregore.ts")
-    .replaceAll("PreToolUse hook (enabled by the launcher via `--enable hooks`)", "`tool_call` gate (loaded after Pi project trust)")
-    .replaceAll("If this Codex build does not support hooks", "If Pi project resources are disabled")
-    .replaceAll("change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.pi/` anytime")
+  // Anchored replacements: every `from` string MUST exist in the generated
+  // Codex spec. A missing anchor once no-opped silently (the tool_call gate
+  // wording vanished from this file for a whole PR cycle before a test caught
+  // it) — now it fails the render loudly so the anchor gets updated alongside
+  // the Codex text that moved.
+  const ANCHORED = [
+    ["Egregore on Codex", "Egregore on Pi"],
+    ["Codex-native", "Pi-native"],
+    ["Codex sessions", "Pi sessions"],
+    ["On Codex", "On Pi"],
+    ["Codex has no", "Pi has no built-in"],
+    ["bin/codex-session-start.sh", "bin/pi-session-start.sh"],
+    [".codex/hooks/branch-guard.js", ".pi/extensions/egregore.ts"],
+    ["PreToolUse hook (launcher `--enable hooks`)", "`tool_call` gate (loaded after Pi project trust)"],
+    ["If this Codex build does not support hooks", "If Pi project resources are disabled"],
+    ["change permissions in `.claude/settings.json` anytime", "review or disable project resources in `.pi/` anytime"],
+  ];
+  let text = sourceSpec;
+  for (const [from, to] of ANCHORED) {
+    if (!text.includes(from)) {
+      throw new Error(`pi-render-spec: anchor not found in generated Codex spec: "${from}" — the Codex wording moved; update this replacement`);
+    }
+    text = text.replaceAll(from, to);
+  }
+  text = text
     .replace(/`\$([a-z][a-z0-9-]*)/g, "`/$1")
     .replace(/\$([a-z][a-z0-9-]*)/g, "/$1");
 
@@ -67,16 +100,9 @@ This appendix is generated from the reviewed shell-runtime translation of \`CLAU
 
   text = replaceSection(text, "On Launch — MANDATORY FIRST ACTION", `The project-local Pi extension renders the Egregore startup card (identity, handoffs, team activity) inside Pi via \`bin/pi-session-start.sh\`. This works for direct \`pi\` launches and launcher-managed sessions. Do not rerun startup checks and do not narrate startup. The card ends with **"What are you working on?"** — that question is already on screen; treat the user's first message as the answer to it. To re-show the card outside Pi, run \`bash bin/pi-session-start.sh --card\`.`);
 
-  text = replaceSection(text, "Command Awareness", `Egregore workflows are available as Pi slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.pi/extensions/egregore.ts\`. Pi also exposes the underlying Agent Skills as \`/skill:name\`, and natural-language requests work normally. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
-
-Invoke commands from user intent — don't wait for the slash. Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Pi, run referenced \`bin/\` scripts directly, use ordinary Pi shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no Pi UI question surface is available.
+  text = prependToSection(text, "Command Awareness", `Egregore workflows are available as Pi slash commands such as \`/activity\`, \`/handoff\`, \`/save\`, and \`/view\`. They are registered from the shared skill inventory by \`.pi/extensions/egregore.ts\`. Pi also exposes the underlying Agent Skills as \`/skill:name\`, and natural-language requests work normally. \`/save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.
 
-**Core loop** — \`/activity\` \`/dashboard\` \`/handoff\` \`/wrap\` \`/save\` \`/reflect\` \`/todo\`
-**Knowledge** — \`/search\` \`/deep-reflect\` \`/archive\` \`/note\` \`/add\` \`/meeting\` \`/ingest\` \`/scroll\`
-**Identity** — \`/me\`
-**Coordination** — \`/ask\` \`/quest\` \`/issue\` \`/invite\` \`/delete-user\` \`/announce\`
-**Git** — \`/branch\` \`/commit\` \`/push\` \`/pr\` \`/save\` \`/review-pr\` \`/contribute\`
-**Infra** — \`/setup\` \`/update\` \`/pull\` \`/env\` \`/infra\` \`/sync-repos\` \`/release\` \`/checkup\``);
+Read the selected skill's \`SKILL.md\` completely before acting. Codex wording inside the shared portable skills means the shell-capable runtime adapter; in Pi, run referenced \`bin/\` scripts directly, use ordinary Pi shell/network access, ignore Codex approval-channel wording, and render compact numbered questions when no Pi UI question surface is available.`, CODEX_COMMAND_LEAD);
 
   return `# Egregore on Pi\n\nThis file is generated by \`bin/pi-render-spec.mjs\`; do not edit it by hand.\n\n${text}\n`;
 }

package/runtime/pi/bin/search.sh

@@ -29,6 +29,48 @@ SLUG=$(jq -r '.slug // "egregore"' "$SCRIPT_DIR/egregore.json" 2>/dev/null || ec
 COLLECTION="${SLUG}-memory"
 MEM_PATH="$(readlink -f "$SCRIPT_DIR/memory" 2>/dev/null || true)"
 
+# qmd 2.5.x may render --full-path results as absolute `**file:**` paths,
+# while older output uses qmd:// URIs. Normalize both to the canonical
+# memory/... form users can open from an Egregore checkout, and parse both
+# forms when counting hits or attaching graph state.
+_normalize_file_paths() {
+  local line absolute_prefix uri_prefix
+  absolute_prefix="**file:** \`$MEM_PATH/"
+  uri_prefix="**file:** \`qmd://${COLLECTION}/"
+  while IFS= read -r line || [ -n "$line" ]; do
+    if [[ "$line" == "$absolute_prefix"* ]]; then
+      printf '**file:** `memory/%s\n' "${line#"$absolute_prefix"}"
+    elif [[ "$line" == "$uri_prefix"* ]]; then
+      printf '**file:** `memory/%s\n' "${line#"$uri_prefix"}"
+    else
+      printf '%s\n' "$line"
+    fi
+  done
+}
+
+_result_paths() {
+  local line path canonical_prefix absolute_prefix uri_prefix
+  canonical_prefix="**file:** \`memory/"
+  absolute_prefix="**file:** \`$MEM_PATH/"
+  uri_prefix="**file:** \`qmd://${COLLECTION}/"
+  while IFS= read -r line || [ -n "$line" ]; do
+    path=""
+    if [[ "$line" == "$canonical_prefix"* ]]; then
+      path="${line#"$canonical_prefix"}"
+    elif [[ "$line" == "$absolute_prefix"* ]]; then
+      path="${line#"$absolute_prefix"}"
+    elif [[ "$line" == "$uri_prefix"* ]]; then
+      path="${line#"$uri_prefix"}"
+    elif [[ "$line" == *"qmd://${COLLECTION}/"* ]]; then
+      path="${line#*"qmd://${COLLECTION}/"}"
+    fi
+    path="${path%%\`*}"
+    case "$path" in
+      *.md*) printf '%s\n' "${path%%.md*}.md" ;;
+    esac
+  done | sort -u
+}
+
 QMD_VERSION="2.5.3"  # pinned — bump deliberately, never float @latest
 
 _qmd() {
@@ -104,7 +146,7 @@ _enrich() {
   local results paths params out
   results=$(cat)
   echo "$results"
-  paths=$(echo "$results" | grep -o "qmd://${COLLECTION}/[^: ]*\.md" | sed "s|qmd://${COLLECTION}/||" | sort -u)
+  paths=$(printf '%s\n' "$results" | _result_paths)
   [ -z "$paths" ] && return 0
   params=$(printf '%s\n' "$paths" | jq -R . | jq -sc '{paths: .}')
   out=$(bash "$SCRIPT_DIR/bin/graph.sh" query "UNWIND \$paths AS fp
@@ -167,7 +209,7 @@ cmd_query() {
   local t0 out label
   t0=$(date +%s)
   if [ "$mode" != "search" ]; then
-    out=$(_qmd "$mode" "$q" -c "$COLLECTION" -n "$n" --format md --full-path "${all[@]}" 2>/dev/null | _clean)
+    out=$(_qmd "$mode" "$q" -c "$COLLECTION" -n "$n" --format md --full-path "${all[@]}" 2>/dev/null | _clean | _normalize_file_paths)
     if [ -n "$out" ] && [ "$out" != "No results found." ]; then
       [ "$mode" = "query" ] && label="hybrid" || label="semantic"
       _banner_and_emit "$label" "$t0" "$emit" "$q" "$out"
@@ -176,7 +218,7 @@ cmd_query() {
     echo "_(hybrid/semantic returned nothing — showing keyword results. If this persists, run: bash bin/search.sh reindex --embed)_"
     echo ""
   fi
-  out=$(_qmd search "$q" -c "$COLLECTION" -n "$n" --format md --full-path "${all[@]}" | _clean)
+  out=$(_qmd search "$q" -c "$COLLECTION" -n "$n" --format md --full-path "${all[@]}" | _clean | _normalize_file_paths)
   _banner_and_emit "keyword" "$t0" "$emit" "$q" "$out"
 }
 
@@ -189,7 +231,7 @@ cmd_query() {
 _banner_and_emit() {
   local label="$1" t0="$2" emit="$3" q="$4" out="$5"
   local hits dur modef product surface plural=""
-  hits=$(printf '%s\n' "$out" | grep -c '^qmd://' 2>/dev/null | tr -d ' ')
+  hits=$(printf '%s\n' "$out" | _result_paths | wc -l | tr -d ' ')
   dur=$(( $(date +%s) - t0 ))
   modef="$label"
   product="Egregore"

package/runtime/pi/bin/session-autosave.sh

@@ -29,6 +29,12 @@
 
 set -uo pipefail
 
+# shellcheck source=bin/lib/git-message.sh
+. "$(cd "$(dirname "$0")" && pwd)/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" "$@"
+}
+
 DIR=""
 AUTHOR=""
 DEBOUNCE=0
@@ -79,7 +85,12 @@ git rev-parse --git-dir >/dev/null 2>&1 || exit 0
 DIR_HASH=$( { md5sum <<<"$DIR" 2>/dev/null || md5 -q -s "$DIR" 2>/dev/null || echo default; } | cut -c1-8 )
 STAMP="/tmp/.egregore-autosave-${DIR_HASH}"
 if [ "$DEBOUNCE" -gt 0 ] && [ -f "$STAMP" ]; then
-  LAST=$(stat -f %m "$STAMP" 2>/dev/null || stat -c %Y "$STAMP" 2>/dev/null || echo 0)
+  if stat -c %Y "$STAMP" >/dev/null 2>&1; then
+    LAST=$(stat -c %Y "$STAMP")
+  else
+    LAST=$(stat -f %m "$STAMP" 2>/dev/null || echo 0)
+  fi
+  case "$LAST" in ""|*[!0-9]*) LAST=0 ;; esac
   [ $(( $(date +%s) - LAST )) -lt "$DEBOUNCE" ] && exit 0
 fi
 touch "$STAMP" 2>/dev/null || true
@@ -118,7 +129,7 @@ fi
 if git -C "$DIR/memory" rev-parse --git-dir >/dev/null 2>&1; then
   if [ -n "$(git -C "$DIR/memory" status --porcelain 2>/dev/null)" ]; then
     git -C "$DIR/memory" add -A >/dev/null 2>&1 || true
-    git -C "$DIR/memory" commit -m "Auto-save: session content" --quiet 2>/dev/null || true
+    egregore_commit "$DIR/memory" "$DIR" "chore(autosave): save session work" --quiet 2>/dev/null || true
   fi
   if [ -n "$(git -C "$DIR/memory" log origin/main..HEAD --oneline 2>/dev/null)" ]; then
     for _try in 1 2 3; do