create-egregore 0.19.22 → 0.19.23

package/assets/egregore-launcher.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// egregore-launcher-version: 0.19.22
+// egregore-launcher-version: 0.19.23
 //
 // egregore — launch and browse Egregore instances from your terminal.
 // Installed by create-egregore. Reads ~/.egregore/instances.json.
@@ -33,7 +33,7 @@ const crypto = require("node:crypto");
 const { spawnSync, spawn } = require("node:child_process");
 const readline = require("node:readline");
 
-const VERSION = "0.19.22";
+const VERSION = "0.19.23";
 const REGISTRY = path.join(os.homedir(), ".egregore", "instances.json");
 const DEFAULT_FILE = path.join(os.homedir(), ".egregore", "default");
 const UPDATE_CACHE_FILE = path.join(os.homedir(), ".egregore", "update-check.json");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-egregore",
-  "version": "0.19.22",
+  "version": "0.19.23",
   "description": "Set up Egregore for your team in one command — installs the egregore launcher and your choice of Claude Code, Codex, or Pi.",
   "license": "MIT",
   "bin": {

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

@@ -22,25 +22,85 @@ an addressed recipient belongs to `$wrap`.
    `name`, then git config.
 3. Parse a short topic and optional recipient from the user request. Match the
    recipient against `memory/people/*.md`; omit the recipient when uncertain.
-4. Draft the markdown body with these sections:
+4. Draft the canonical markdown record with frontmatter and these sections:
    - `## Briefing`
    - `## Key Decisions`
    - `## Current State`
    - `## Open Threads`
    - `## Next Steps`
    - `## Entry Points`
-5. Write the body to a temp file, then run one orchestration command:
+   Use this metadata contract even when the user supplied only prose:
+
+```markdown
+---
+capture_schema: egregore-capture/v1
+capture_mode: addressed
+kind: addressed
+from: <author>
+addressed_to: <recipient, if any>
+date: YYYY-MM-DD
+topic: <topic>
+intent: <action | feedback | fyi>
+claim: <one-line claim>
+ask: <what the receiver should do>
+---
+```
+
+5. Compose the HTML view from that record. Markdown is canonical; the JSON is
+   only a presentation map. Give every JSON section a stable `id` and add a
+   top-level `sourceMap` from every authored `##` heading to the section that
+   contains its complete text:
+
+```json
+{
+  "kind": "handoff",
+  "kicker": "Handoff",
+  "topic": "<topic>",
+  "claim": "<one-line claim>",
+  "sourceMap": {
+    "Briefing": "briefing",
+    "Key Decisions": "decisions",
+    "Current State": "current-state",
+    "Open Threads": "open-threads",
+    "Next Steps": "next-steps",
+    "Entry Points": "entry-points"
+  },
+  "sections": [
+    {"id":"briefing","label":"Briefing","component":"prose","body":"<complete Briefing text>"}
+  ]
+}
+```
+
+   Pick richer components when they fit, but copy all authored content into
+   the mapped destination. Never independently summarize the Markdown into the
+   JSON. For command-heavy sections, keep command headings, explanatory text,
+   fenced commands, and expected output verbatim.
+
+6. Render the actual HTML with semantic coverage enabled and show it before
+   publishing. This is the approval surface—not a list of component names:
+
+```bash
+node packages/egregore-artifacts/bin/cli.js composed "$COMPOSED_FILE" \
+  --source "$BODY_FILE" --verify-fidelity
+```
+
+   Stop for confirmation after the browser preview. If validation fails, fix
+   the mapping/content and render again. Skip confirmation only when the user
+   explicitly said to send without preview.
+
+7. After confirmation, run one orchestration command:
 
 ```bash
 TMPDIR="$(mktemp -d -t codex-handoff-XXXXXX)"
-TMPDIR="$TMPDIR" bash bin/capture-run.sh --mode addressed --author "$AUTHOR" --topic "$TOPIC" ${RECIPIENT_ARG} < "$BODY_FILE"
+TMPDIR="$TMPDIR" bash bin/capture-run.sh --mode addressed --author "$AUTHOR" \
+  --topic "$TOPIC" ${RECIPIENT_ARG} --composed "$COMPOSED_FILE" < "$BODY_FILE"
 ```
 
 Use `--recipient "$RECIPIENT"` only when a clear teammate or future-self
 recipient is known. Do not pass `--no-publish` unless the user explicitly
 asked for a dry run. The runner may plan a notification, but never dispatches.
 
-6. Read `$TMPDIR/handoff-run-result.json` and render:
+8. Read `$TMPDIR/handoff-run-result.json` and render:
 
 ```bash
 node bin/codex-skill-render.mjs handoff-card "$TMPDIR/handoff-run-result.json"
@@ -50,20 +110,20 @@ Paste the rendered card exactly in the visible response, preferably in a
 `text` fenced block. Do not paraphrase the card into bullets unless the user
 asks for a summary.
 
-7. If the result has `notifyStatus: "approval_required"`, follow
+9. If the result has `notifyStatus: "approval_required"`, follow
    `.claude/context/notification-consent.md`. In a separate checkpoint, show
    the exact organization, recipient/group, every channel/delivery, and exact
    message from `notifyPlan`; offer Send / Edit / Cancel and wait. Only a Send
    response to that preview permits one `approve` + `dispatch`. A local direct
    message never falls back to a group.
 
-8. Fire the detached save helper when appropriate:
+10. Fire the detached save helper when appropriate:
 
 ```bash
 ( bash bin/handoff-save-egregore.sh "$AUTHOR" "$TOPIC" >/dev/null 2>&1 & ) >/dev/null 2>&1
 ```
 
-9. Report the `memory/...` path and hosted link from the result JSON when a
+11. Report the `memory/...` path and hosted link from the result JSON when a
    link exists.
 
 ## Rules
@@ -72,6 +132,8 @@ asks for a summary.
 - Do not use Claude Code commands.
 - Keep the briefing concise and operational; include exact files, branches,
   commands, open questions, and verification state when relevant.
+- The artifact is a view of the handoff, never a summary of it. Publishing
+  must fail when any non-empty authored section is unmapped or loses content.
 - Structured UX parity is required: the rendered card is the acknowledgment.
   Do not add a preamble such as "Handoff created successfully." Preserve the
   72-column TUI/card shape, status footer, links below the box, and warning

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

@@ -309,6 +309,7 @@ function renderHandoff(data) {
     data.graphStatus ? `graph=${data.graphStatus}` : '',
     data.memoryStatus ? `memory=${data.memoryStatus}` : '',
     data.notifyStatus ? `notify=${data.notifyStatus}` : '',
+    data.publishStatus ? `publish=${data.publishStatus}` : '',
   ].filter(Boolean).join(' · ');
 
   const lines = [topRule(), padLine('⇌ HANDOFF', data.author || ''), rule()];
@@ -317,6 +318,10 @@ function renderHandoff(data) {
   if (file) lines.push(padLine(`Path: ${file}`));
   if (data.artifactUrl) lines.push(padLine(`Link: ${data.artifactUrl}`));
   if (statuses) lines.push(padLine(statuses));
+  if (data.publishStatus === 'fidelity-failed') {
+    lines.push(rule());
+    lines.push(padLine('Artifact not published — restore missing content and preview again.'));
+  }
   lines.push(bottomRule());
   return lines.join('\n');
 }

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

@@ -122,87 +122,62 @@ if [ ! -s "$ABS_FILE" ]; then
   exit 1
 fi
 
-# --- Canonical capture contract -----------------------------------------
-# /handoff is the addressed door into the shared capture engine. Persist the
-# same schema/mode fields used by /wrap and SessionEnd so filesystem and graph
-# retrieval can distinguish captures without inferring from directory names.
-if ! grep -qiE '^(capture_schema:|\*\*[Cc]apture [Ss]chema\*\*:)' "$ABS_FILE"; then
-  CAPTURE_KIND=""
-  if ! grep -qiE '^(kind:|\*\*[Kk]ind\*\*:)' "$ABS_FILE"; then
-    CAPTURE_KIND="addressed"
-  fi
-  if [ "$(head -1 "$ABS_FILE")" = "---" ]; then
-    awk -v kind="$CAPTURE_KIND" '
-      NR == 1 {
-        print
-        print "capture_schema: egregore-capture/v1"
-        print "capture_mode: addressed"
-        if (kind != "") print "kind: " kind
-        next
-      }
-      { print }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  else
-    awk -v kind="$CAPTURE_KIND" '
-      !injected && /^\*\*[Aa]uthor\*\*:/ {
-        print
-        print "**Capture Schema**: egregore-capture/v1"
-        print "**Capture Mode**: addressed"
-        if (kind != "") print "**Kind**: " kind
-        injected=1
-        next
-      }
-      { print }
-      END {
-        if (!injected) {
-          print "**Capture Schema**: egregore-capture/v1"
-          print "**Capture Mode**: addressed"
-          if (kind != "") print "**Kind**: " kind
-        }
-      }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  fi
-fi
+# --- Canonical metadata boundary ----------------------------------------
+# Callers are allowed to send prose-only markdown, but persisted handoffs are
+# not. Normalize every input to the same frontmatter contract before indexing
+# or rendering so title/author/recipient cannot disappear at the adapter seam.
+HAS_FRONTMATTER=0
+[ "$(head -1 "$ABS_FILE")" = "---" ] && HAS_FRONTMATTER=1
+
+_has_frontmatter_key() {
+  [ "$HAS_FRONTMATTER" = "1" ] && sed -n '2,/^---$/p' "$ABS_FILE" | grep -qiE "^${1}:"
+}
 
-# --- Inject **To**: line if --recipient given and body omits it -----
-# index-handoff.sh parses recipients from the file body. Skills
-# normally write the To line themselves, but callers that invoke
-# handoff-run.sh directly often skip it. Inject after the Author
-# line so the graph gets the HANDED_TO edge.
-if [ -n "$RECIPIENT" ] && ! grep -qi "^\*\*[Tt]o\*\*:" "$ABS_FILE"; then
-  awk -v r="$RECIPIENT" '
-    !injected && /^\*\*[Aa]uthor\*\*:/ {
-      print
-      print "**To**: " r
-      injected=1
-      next
-    }
-    { print }
-  ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
+MISSING_SCHEMA=0;    _has_frontmatter_key capture_schema || MISSING_SCHEMA=1
+MISSING_MODE=0;      _has_frontmatter_key capture_mode || MISSING_MODE=1
+MISSING_KIND=0;      _has_frontmatter_key kind || MISSING_KIND=1
+MISSING_FROM=0;      _has_frontmatter_key from || _has_frontmatter_key author || MISSING_FROM=1
+MISSING_DATE=0;      _has_frontmatter_key date || MISSING_DATE=1
+MISSING_TOPIC=0;     _has_frontmatter_key topic || MISSING_TOPIC=1
+MISSING_INTENT=0;    _has_frontmatter_key intent || MISSING_INTENT=1
+MISSING_RECIPIENT=0
+if [ -n "$RECIPIENT" ]; then
+  _has_frontmatter_key addressed_to || _has_frontmatter_key to || MISSING_RECIPIENT=1
 fi
 
-# --- Persist lifecycle intent in the canonical handoff file -------------
-if ! grep -qiE '^(intent:|\*\*[Ii]ntent\*\*:)' "$ABS_FILE"; then
-  if [ "$(head -1 "$ABS_FILE")" = "---" ]; then
-    awk -v intent="$INTENT" '
-      NR == 1 { print; print "intent: " intent; next }
-      { print }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  else
-    awk -v intent="$INTENT" '
-      !injected && /^\*\*[Aa]uthor\*\*:/ {
-        print
-        print "**Intent**: " intent
-        injected=1
-        next
-      }
-      { print }
-      END {
-        if (!injected) print "**Intent**: " intent
-      }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  fi
-fi
+awk \
+  -v has_frontmatter="$HAS_FRONTMATTER" \
+  -v schema="$MISSING_SCHEMA" -v mode="$MISSING_MODE" -v kind="$MISSING_KIND" \
+  -v from="$MISSING_FROM" -v date_missing="$MISSING_DATE" \
+  -v topic_missing="$MISSING_TOPIC" -v intent_missing="$MISSING_INTENT" \
+  -v recipient_missing="$MISSING_RECIPIENT" \
+  -v author="$AUTHOR" -v date="$TODAY" -v topic="$TOPIC" \
+  -v intent="$INTENT" -v recipient="$RECIPIENT" '
+  function metadata() {
+    if (schema) print "capture_schema: egregore-capture/v1"
+    if (mode) print "capture_mode: addressed"
+    if (kind) print "kind: addressed"
+    if (from) print "from: " author
+    if (recipient_missing) print "addressed_to: " recipient
+    if (date_missing) print "date: " date
+    if (topic_missing) print "topic: " topic
+    if (intent_missing) print "intent: " intent
+  }
+  BEGIN {
+    if (!has_frontmatter) {
+      print "---"
+      metadata()
+      print "---"
+      print ""
+    }
+  }
+  has_frontmatter && NR == 1 {
+    print
+    metadata()
+    next
+  }
+  { print }
+' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
 
 # --- Append repo state ---------------------------------------------------
 # --no-pr skips `gh pr list` (~400–600ms per repo). A detached PR backfill
@@ -401,12 +376,16 @@ PID_MEMORY=$!
       RENDERED_HTML="$TMPD/handoff.html"
       RENDER_OK=0
       LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+      FIDELITY_ARGS=(--verify-fidelity)
+      if [ "$RENDER_TYPE" = "composed" ]; then
+        FIDELITY_ARGS+=(--source "$ABS_FILE")
+      fi
       if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-        if node "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" --output "$RENDERED_HTML" >/dev/null 2>&1; then
+        if node "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
           RENDER_OK=1
         fi
       else
-        if npx egregore-artifacts "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" --output "$RENDERED_HTML" >/dev/null 2>&1; then
+        if npx -y egregore-artifacts@latest "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
           RENDER_OK=1
         fi
       fi
@@ -481,9 +460,11 @@ PID_MEMORY=$!
   PUBLISH_RC=0
   if [ -z "$V1URL" ] && [ "$NO_PUBLISH" = "0" ] && [ -x "$SCRIPT_DIR/bin/publish-artifact.sh" ]; then
     AURL=$(bash "$SCRIPT_DIR/bin/publish-artifact.sh" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" \
+      --verify-fidelity \
+      --source "$ABS_FILE" \
       --title "$TOPIC" \
       --author "$AUTHOR" \
-      --description "$BRIEFING_LEAD" 2>/dev/null) || PUBLISH_RC=$?
+      --description "$BRIEFING_LEAD" 2>"$TMPD/publish-error") || PUBLISH_RC=$?
   fi
 
   PS="published"
@@ -495,6 +476,8 @@ PID_MEMORY=$!
     PS="relay-off"
   elif [ "$PUBLISH_RC" = "3" ]; then
     PS="hosting-off"
+  elif grep -q 'Handoff fidelity check failed' "$TMPD/render-error" "$TMPD/publish-error" 2>/dev/null; then
+    PS="fidelity-failed"
   else
     PS="failed"
   fi
@@ -614,6 +597,7 @@ STATUS_BITS=("saved")
 [ "$NOTIFY_STATUS" = "approval_required" ] && STATUS_BITS+=("notify approval pending")
 [ -n "$ARTIFACT_URL" ]         && STATUS_BITS+=("published")
 [ "$PUBLISH_STATUS" = "relay-off" ] && STATUS_BITS+=("not published")
+[ "$PUBLISH_STATUS" = "fidelity-failed" ] && STATUS_BITS+=("artifact fidelity failed")
 
 STATUS_LINE=""
 for bit in "${STATUS_BITS[@]}"; do

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

@@ -119,11 +119,12 @@ AUTHOR="$(md_field 'Author')"
 AUTHOR_HANDLE="$(echo "$AUTHOR" | sed 's/[[:space:]]*→.*//' | awk '{print tolower($1)}')"
 [ -z "$AUTHOR_HANDLE" ] && AUTHOR_HANDLE="unknown"
 
-# Recipients: try markdown header (To or For), then YAML (to or for)
+# Recipients: try markdown header, then canonical/legacy YAML names.
 RECIPIENTS_RAW="$(md_field 'To')"
 [ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(md_field 'For')"
 [ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'to')"
 [ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'for')"
+[ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'addressed_to')"
 # Also extract from "From: author → recipient" pattern
 if [ -z "$RECIPIENTS_RAW" ] && echo "$AUTHOR" | grep -q '→' 2>/dev/null; then
   RECIPIENTS_RAW="$(echo "$AUTHOR" | sed 's/.*→[[:space:]]*//')"

package/runtime/codex/bin/publish-artifact.sh

@@ -27,6 +27,7 @@ set -euo pipefail
 #             3 hosting turned off (features.publishing=false)
 #             4 nothing uploaded — public relay not enabled and no org API key,
 #               or egregore.json is missing/unreadable (fail closed)
+#             5 renderer/fidelity validation failed (nothing uploaded)
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 CONFIG="$SCRIPT_DIR/egregore.json"
@@ -41,6 +42,8 @@ ARTIFACT_ID=""
 RAW_HTML=0
 SKIP_REFERENCES=0
 PAIR=""
+VERIFY_FIDELITY=0
+FIDELITY_SOURCE=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -49,6 +52,8 @@ while [[ $# -gt 0 ]]; do
     --description) DESCRIPTION="$2"; shift 2 ;;
     --id) ARTIFACT_ID="$2"; shift 2 ;;
     --pair) PAIR="$2"; shift 2 ;;
+    --verify-fidelity) VERIFY_FIDELITY=1; shift ;;
+    --source) FIDELITY_SOURCE="$2"; shift 2 ;;
     --raw-html) RAW_HTML=1; shift ;;
     --no-references) SKIP_REFERENCES=1; shift ;;
     *)
@@ -165,6 +170,16 @@ else
   if [ -n "$PAIR" ]; then
     RENDER_ARGS+=(--pair "$PAIR")
   fi
+  if [ "$VERIFY_FIDELITY" -eq 1 ]; then
+    RENDER_ARGS+=(--verify-fidelity)
+    if [ "$TYPE" = "composed" ]; then
+      [ -n "$FIDELITY_SOURCE" ] || {
+        echo "Handoff fidelity check requires --source <canonical-handoff.md>" >&2
+        exit 1
+      }
+      RENDER_ARGS+=(--source "$FIDELITY_SOURCE")
+    fi
+  fi
 
   # Prefer the in-repo package copy when it's present AND its dependencies
   # have been installed — that way local edits to packages/egregore-artifacts
@@ -174,15 +189,21 @@ else
   # when a local install is present — useful in the upstream dev repo to
   # dogfood what teammates and OSS users actually run.
   LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+  RENDER_ERROR="/tmp/egregore-artifacts/render-error-$$.log"
   if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-    if ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>&1; then
-      exit 0
+    if ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+      sed -n '1,4p' "$RENDER_ERROR" >&2
+      rm -f "$RENDER_ERROR"
+      exit 5
     fi
   else
-    if ! npx egregore-artifacts@latest "${RENDER_ARGS[@]}" >/dev/null 2>&1; then
-      exit 0
+    if ! npx -y egregore-artifacts@latest "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+      sed -n '1,4p' "$RENDER_ERROR" >&2
+      rm -f "$RENDER_ERROR"
+      exit 5
     fi
   fi
+  rm -f "$RENDER_ERROR"
 fi
 
 if [ ! -f "$TMP_HTML" ]; then

package/runtime/pi/.codex/skills/handoff/SKILL.md

@@ -22,25 +22,85 @@ an addressed recipient belongs to `$wrap`.
    `name`, then git config.
 3. Parse a short topic and optional recipient from the user request. Match the
    recipient against `memory/people/*.md`; omit the recipient when uncertain.
-4. Draft the markdown body with these sections:
+4. Draft the canonical markdown record with frontmatter and these sections:
    - `## Briefing`
    - `## Key Decisions`
    - `## Current State`
    - `## Open Threads`
    - `## Next Steps`
    - `## Entry Points`
-5. Write the body to a temp file, then run one orchestration command:
+   Use this metadata contract even when the user supplied only prose:
+
+```markdown
+---
+capture_schema: egregore-capture/v1
+capture_mode: addressed
+kind: addressed
+from: <author>
+addressed_to: <recipient, if any>
+date: YYYY-MM-DD
+topic: <topic>
+intent: <action | feedback | fyi>
+claim: <one-line claim>
+ask: <what the receiver should do>
+---
+```
+
+5. Compose the HTML view from that record. Markdown is canonical; the JSON is
+   only a presentation map. Give every JSON section a stable `id` and add a
+   top-level `sourceMap` from every authored `##` heading to the section that
+   contains its complete text:
+
+```json
+{
+  "kind": "handoff",
+  "kicker": "Handoff",
+  "topic": "<topic>",
+  "claim": "<one-line claim>",
+  "sourceMap": {
+    "Briefing": "briefing",
+    "Key Decisions": "decisions",
+    "Current State": "current-state",
+    "Open Threads": "open-threads",
+    "Next Steps": "next-steps",
+    "Entry Points": "entry-points"
+  },
+  "sections": [
+    {"id":"briefing","label":"Briefing","component":"prose","body":"<complete Briefing text>"}
+  ]
+}
+```
+
+   Pick richer components when they fit, but copy all authored content into
+   the mapped destination. Never independently summarize the Markdown into the
+   JSON. For command-heavy sections, keep command headings, explanatory text,
+   fenced commands, and expected output verbatim.
+
+6. Render the actual HTML with semantic coverage enabled and show it before
+   publishing. This is the approval surface—not a list of component names:
+
+```bash
+node packages/egregore-artifacts/bin/cli.js composed "$COMPOSED_FILE" \
+  --source "$BODY_FILE" --verify-fidelity
+```
+
+   Stop for confirmation after the browser preview. If validation fails, fix
+   the mapping/content and render again. Skip confirmation only when the user
+   explicitly said to send without preview.
+
+7. After confirmation, run one orchestration command:
 
 ```bash
 TMPDIR="$(mktemp -d -t codex-handoff-XXXXXX)"
-TMPDIR="$TMPDIR" bash bin/capture-run.sh --mode addressed --author "$AUTHOR" --topic "$TOPIC" ${RECIPIENT_ARG} < "$BODY_FILE"
+TMPDIR="$TMPDIR" bash bin/capture-run.sh --mode addressed --author "$AUTHOR" \
+  --topic "$TOPIC" ${RECIPIENT_ARG} --composed "$COMPOSED_FILE" < "$BODY_FILE"
 ```
 
 Use `--recipient "$RECIPIENT"` only when a clear teammate or future-self
 recipient is known. Do not pass `--no-publish` unless the user explicitly
 asked for a dry run. The runner may plan a notification, but never dispatches.
 
-6. Read `$TMPDIR/handoff-run-result.json` and render:
+8. Read `$TMPDIR/handoff-run-result.json` and render:
 
 ```bash
 node bin/codex-skill-render.mjs handoff-card "$TMPDIR/handoff-run-result.json"
@@ -50,20 +110,20 @@ Paste the rendered card exactly in the visible response, preferably in a
 `text` fenced block. Do not paraphrase the card into bullets unless the user
 asks for a summary.
 
-7. If the result has `notifyStatus: "approval_required"`, follow
+9. If the result has `notifyStatus: "approval_required"`, follow
    `.claude/context/notification-consent.md`. In a separate checkpoint, show
    the exact organization, recipient/group, every channel/delivery, and exact
    message from `notifyPlan`; offer Send / Edit / Cancel and wait. Only a Send
    response to that preview permits one `approve` + `dispatch`. A local direct
    message never falls back to a group.
 
-8. Fire the detached save helper when appropriate:
+10. Fire the detached save helper when appropriate:
 
 ```bash
 ( bash bin/handoff-save-egregore.sh "$AUTHOR" "$TOPIC" >/dev/null 2>&1 & ) >/dev/null 2>&1
 ```
 
-9. Report the `memory/...` path and hosted link from the result JSON when a
+11. Report the `memory/...` path and hosted link from the result JSON when a
    link exists.
 
 ## Rules
@@ -72,6 +132,8 @@ asks for a summary.
 - Do not use Claude Code commands.
 - Keep the briefing concise and operational; include exact files, branches,
   commands, open questions, and verification state when relevant.
+- The artifact is a view of the handoff, never a summary of it. Publishing
+  must fail when any non-empty authored section is unmapped or loses content.
 - Structured UX parity is required: the rendered card is the acknowledgment.
   Do not add a preamble such as "Handoff created successfully." Preserve the
   72-column TUI/card shape, status footer, links below the box, and warning

package/runtime/pi/bin/codex-skill-render.mjs

@@ -309,6 +309,7 @@ function renderHandoff(data) {
     data.graphStatus ? `graph=${data.graphStatus}` : '',
     data.memoryStatus ? `memory=${data.memoryStatus}` : '',
     data.notifyStatus ? `notify=${data.notifyStatus}` : '',
+    data.publishStatus ? `publish=${data.publishStatus}` : '',
   ].filter(Boolean).join(' · ');
 
   const lines = [topRule(), padLine('⇌ HANDOFF', data.author || ''), rule()];
@@ -317,6 +318,10 @@ function renderHandoff(data) {
   if (file) lines.push(padLine(`Path: ${file}`));
   if (data.artifactUrl) lines.push(padLine(`Link: ${data.artifactUrl}`));
   if (statuses) lines.push(padLine(statuses));
+  if (data.publishStatus === 'fidelity-failed') {
+    lines.push(rule());
+    lines.push(padLine('Artifact not published — restore missing content and preview again.'));
+  }
   lines.push(bottomRule());
   return lines.join('\n');
 }

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

@@ -122,87 +122,62 @@ if [ ! -s "$ABS_FILE" ]; then
   exit 1
 fi
 
-# --- Canonical capture contract -----------------------------------------
-# /handoff is the addressed door into the shared capture engine. Persist the
-# same schema/mode fields used by /wrap and SessionEnd so filesystem and graph
-# retrieval can distinguish captures without inferring from directory names.
-if ! grep -qiE '^(capture_schema:|\*\*[Cc]apture [Ss]chema\*\*:)' "$ABS_FILE"; then
-  CAPTURE_KIND=""
-  if ! grep -qiE '^(kind:|\*\*[Kk]ind\*\*:)' "$ABS_FILE"; then
-    CAPTURE_KIND="addressed"
-  fi
-  if [ "$(head -1 "$ABS_FILE")" = "---" ]; then
-    awk -v kind="$CAPTURE_KIND" '
-      NR == 1 {
-        print
-        print "capture_schema: egregore-capture/v1"
-        print "capture_mode: addressed"
-        if (kind != "") print "kind: " kind
-        next
-      }
-      { print }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  else
-    awk -v kind="$CAPTURE_KIND" '
-      !injected && /^\*\*[Aa]uthor\*\*:/ {
-        print
-        print "**Capture Schema**: egregore-capture/v1"
-        print "**Capture Mode**: addressed"
-        if (kind != "") print "**Kind**: " kind
-        injected=1
-        next
-      }
-      { print }
-      END {
-        if (!injected) {
-          print "**Capture Schema**: egregore-capture/v1"
-          print "**Capture Mode**: addressed"
-          if (kind != "") print "**Kind**: " kind
-        }
-      }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  fi
-fi
+# --- Canonical metadata boundary ----------------------------------------
+# Callers are allowed to send prose-only markdown, but persisted handoffs are
+# not. Normalize every input to the same frontmatter contract before indexing
+# or rendering so title/author/recipient cannot disappear at the adapter seam.
+HAS_FRONTMATTER=0
+[ "$(head -1 "$ABS_FILE")" = "---" ] && HAS_FRONTMATTER=1
+
+_has_frontmatter_key() {
+  [ "$HAS_FRONTMATTER" = "1" ] && sed -n '2,/^---$/p' "$ABS_FILE" | grep -qiE "^${1}:"
+}
 
-# --- Inject **To**: line if --recipient given and body omits it -----
-# index-handoff.sh parses recipients from the file body. Skills
-# normally write the To line themselves, but callers that invoke
-# handoff-run.sh directly often skip it. Inject after the Author
-# line so the graph gets the HANDED_TO edge.
-if [ -n "$RECIPIENT" ] && ! grep -qi "^\*\*[Tt]o\*\*:" "$ABS_FILE"; then
-  awk -v r="$RECIPIENT" '
-    !injected && /^\*\*[Aa]uthor\*\*:/ {
-      print
-      print "**To**: " r
-      injected=1
-      next
-    }
-    { print }
-  ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
+MISSING_SCHEMA=0;    _has_frontmatter_key capture_schema || MISSING_SCHEMA=1
+MISSING_MODE=0;      _has_frontmatter_key capture_mode || MISSING_MODE=1
+MISSING_KIND=0;      _has_frontmatter_key kind || MISSING_KIND=1
+MISSING_FROM=0;      _has_frontmatter_key from || _has_frontmatter_key author || MISSING_FROM=1
+MISSING_DATE=0;      _has_frontmatter_key date || MISSING_DATE=1
+MISSING_TOPIC=0;     _has_frontmatter_key topic || MISSING_TOPIC=1
+MISSING_INTENT=0;    _has_frontmatter_key intent || MISSING_INTENT=1
+MISSING_RECIPIENT=0
+if [ -n "$RECIPIENT" ]; then
+  _has_frontmatter_key addressed_to || _has_frontmatter_key to || MISSING_RECIPIENT=1
 fi
 
-# --- Persist lifecycle intent in the canonical handoff file -------------
-if ! grep -qiE '^(intent:|\*\*[Ii]ntent\*\*:)' "$ABS_FILE"; then
-  if [ "$(head -1 "$ABS_FILE")" = "---" ]; then
-    awk -v intent="$INTENT" '
-      NR == 1 { print; print "intent: " intent; next }
-      { print }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  else
-    awk -v intent="$INTENT" '
-      !injected && /^\*\*[Aa]uthor\*\*:/ {
-        print
-        print "**Intent**: " intent
-        injected=1
-        next
-      }
-      { print }
-      END {
-        if (!injected) print "**Intent**: " intent
-      }
-    ' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
-  fi
-fi
+awk \
+  -v has_frontmatter="$HAS_FRONTMATTER" \
+  -v schema="$MISSING_SCHEMA" -v mode="$MISSING_MODE" -v kind="$MISSING_KIND" \
+  -v from="$MISSING_FROM" -v date_missing="$MISSING_DATE" \
+  -v topic_missing="$MISSING_TOPIC" -v intent_missing="$MISSING_INTENT" \
+  -v recipient_missing="$MISSING_RECIPIENT" \
+  -v author="$AUTHOR" -v date="$TODAY" -v topic="$TOPIC" \
+  -v intent="$INTENT" -v recipient="$RECIPIENT" '
+  function metadata() {
+    if (schema) print "capture_schema: egregore-capture/v1"
+    if (mode) print "capture_mode: addressed"
+    if (kind) print "kind: addressed"
+    if (from) print "from: " author
+    if (recipient_missing) print "addressed_to: " recipient
+    if (date_missing) print "date: " date
+    if (topic_missing) print "topic: " topic
+    if (intent_missing) print "intent: " intent
+  }
+  BEGIN {
+    if (!has_frontmatter) {
+      print "---"
+      metadata()
+      print "---"
+      print ""
+    }
+  }
+  has_frontmatter && NR == 1 {
+    print
+    metadata()
+    next
+  }
+  { print }
+' "$ABS_FILE" > "$ABS_FILE.new" && mv "$ABS_FILE.new" "$ABS_FILE"
 
 # --- Append repo state ---------------------------------------------------
 # --no-pr skips `gh pr list` (~400–600ms per repo). A detached PR backfill
@@ -401,12 +376,16 @@ PID_MEMORY=$!
       RENDERED_HTML="$TMPD/handoff.html"
       RENDER_OK=0
       LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+      FIDELITY_ARGS=(--verify-fidelity)
+      if [ "$RENDER_TYPE" = "composed" ]; then
+        FIDELITY_ARGS+=(--source "$ABS_FILE")
+      fi
       if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-        if node "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" --output "$RENDERED_HTML" >/dev/null 2>&1; then
+        if node "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
           RENDER_OK=1
         fi
       else
-        if npx egregore-artifacts "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" --output "$RENDERED_HTML" >/dev/null 2>&1; then
+        if npx -y egregore-artifacts@latest "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" "${FIDELITY_ARGS[@]}" --output "$RENDERED_HTML" >/dev/null 2>"$TMPD/render-error"; then
           RENDER_OK=1
         fi
       fi
@@ -481,9 +460,11 @@ PID_MEMORY=$!
   PUBLISH_RC=0
   if [ -z "$V1URL" ] && [ "$NO_PUBLISH" = "0" ] && [ -x "$SCRIPT_DIR/bin/publish-artifact.sh" ]; then
     AURL=$(bash "$SCRIPT_DIR/bin/publish-artifact.sh" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" \
+      --verify-fidelity \
+      --source "$ABS_FILE" \
       --title "$TOPIC" \
       --author "$AUTHOR" \
-      --description "$BRIEFING_LEAD" 2>/dev/null) || PUBLISH_RC=$?
+      --description "$BRIEFING_LEAD" 2>"$TMPD/publish-error") || PUBLISH_RC=$?
   fi
 
   PS="published"
@@ -495,6 +476,8 @@ PID_MEMORY=$!
     PS="relay-off"
   elif [ "$PUBLISH_RC" = "3" ]; then
     PS="hosting-off"
+  elif grep -q 'Handoff fidelity check failed' "$TMPD/render-error" "$TMPD/publish-error" 2>/dev/null; then
+    PS="fidelity-failed"
   else
     PS="failed"
   fi
@@ -614,6 +597,7 @@ STATUS_BITS=("saved")
 [ "$NOTIFY_STATUS" = "approval_required" ] && STATUS_BITS+=("notify approval pending")
 [ -n "$ARTIFACT_URL" ]         && STATUS_BITS+=("published")
 [ "$PUBLISH_STATUS" = "relay-off" ] && STATUS_BITS+=("not published")
+[ "$PUBLISH_STATUS" = "fidelity-failed" ] && STATUS_BITS+=("artifact fidelity failed")
 
 STATUS_LINE=""
 for bit in "${STATUS_BITS[@]}"; do

package/runtime/pi/bin/index-handoff.sh

@@ -119,11 +119,12 @@ AUTHOR="$(md_field 'Author')"
 AUTHOR_HANDLE="$(echo "$AUTHOR" | sed 's/[[:space:]]*→.*//' | awk '{print tolower($1)}')"
 [ -z "$AUTHOR_HANDLE" ] && AUTHOR_HANDLE="unknown"
 
-# Recipients: try markdown header (To or For), then YAML (to or for)
+# Recipients: try markdown header, then canonical/legacy YAML names.
 RECIPIENTS_RAW="$(md_field 'To')"
 [ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(md_field 'For')"
 [ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'to')"
 [ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'for')"
+[ -z "$RECIPIENTS_RAW" ] && RECIPIENTS_RAW="$(yaml_extract 'addressed_to')"
 # Also extract from "From: author → recipient" pattern
 if [ -z "$RECIPIENTS_RAW" ] && echo "$AUTHOR" | grep -q '→' 2>/dev/null; then
   RECIPIENTS_RAW="$(echo "$AUTHOR" | sed 's/.*→[[:space:]]*//')"

package/runtime/pi/bin/pi-product-workflows.mjs

@@ -199,14 +199,23 @@ function section(title, body) {
 }
 
 export function buildHandoffDocument(params, author, date = new Date().toISOString().slice(0, 10)) {
+  const topic = cleanArgs(params.topic);
+  const recipient = cleanArgs(params.recipient);
   const lines = [
-    `# Handoff: ${cleanArgs(params.topic)}`,
-    "",
-    `**Date**: ${date}`,
-    `**Author**: ${author}`,
+    "---",
+    "capture_schema: egregore-capture/v1",
+    "capture_mode: addressed",
+    "kind: addressed",
+    `from: ${author}`,
   ];
-  if (cleanArgs(params.recipient)) lines.push(`**To**: ${cleanArgs(params.recipient)}`);
+  if (recipient) lines.push(`addressed_to: ${recipient}`);
   lines.push(
+    `date: ${date}`,
+    `topic: ${topic}`,
+    "intent: action",
+    "---",
+    "",
+    `# Handoff: ${topic}`,
     "",
     section("Briefing", params.briefing),
     "",

package/runtime/pi/bin/publish-artifact.sh

@@ -27,6 +27,7 @@ set -euo pipefail
 #             3 hosting turned off (features.publishing=false)
 #             4 nothing uploaded — public relay not enabled and no org API key,
 #               or egregore.json is missing/unreadable (fail closed)
+#             5 renderer/fidelity validation failed (nothing uploaded)
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 CONFIG="$SCRIPT_DIR/egregore.json"
@@ -41,6 +42,8 @@ ARTIFACT_ID=""
 RAW_HTML=0
 SKIP_REFERENCES=0
 PAIR=""
+VERIFY_FIDELITY=0
+FIDELITY_SOURCE=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -49,6 +52,8 @@ while [[ $# -gt 0 ]]; do
     --description) DESCRIPTION="$2"; shift 2 ;;
     --id) ARTIFACT_ID="$2"; shift 2 ;;
     --pair) PAIR="$2"; shift 2 ;;
+    --verify-fidelity) VERIFY_FIDELITY=1; shift ;;
+    --source) FIDELITY_SOURCE="$2"; shift 2 ;;
     --raw-html) RAW_HTML=1; shift ;;
     --no-references) SKIP_REFERENCES=1; shift ;;
     *)
@@ -165,6 +170,16 @@ else
   if [ -n "$PAIR" ]; then
     RENDER_ARGS+=(--pair "$PAIR")
   fi
+  if [ "$VERIFY_FIDELITY" -eq 1 ]; then
+    RENDER_ARGS+=(--verify-fidelity)
+    if [ "$TYPE" = "composed" ]; then
+      [ -n "$FIDELITY_SOURCE" ] || {
+        echo "Handoff fidelity check requires --source <canonical-handoff.md>" >&2
+        exit 1
+      }
+      RENDER_ARGS+=(--source "$FIDELITY_SOURCE")
+    fi
+  fi
 
   # Prefer the in-repo package copy when it's present AND its dependencies
   # have been installed — that way local edits to packages/egregore-artifacts
@@ -174,15 +189,21 @@ else
   # when a local install is present — useful in the upstream dev repo to
   # dogfood what teammates and OSS users actually run.
   LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+  RENDER_ERROR="/tmp/egregore-artifacts/render-error-$$.log"
   if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
-    if ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>&1; then
-      exit 0
+    if ! node "$LOCAL_CLI" "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+      sed -n '1,4p' "$RENDER_ERROR" >&2
+      rm -f "$RENDER_ERROR"
+      exit 5
     fi
   else
-    if ! npx egregore-artifacts@latest "${RENDER_ARGS[@]}" >/dev/null 2>&1; then
-      exit 0
+    if ! npx -y egregore-artifacts@latest "${RENDER_ARGS[@]}" >/dev/null 2>"$RENDER_ERROR"; then
+      sed -n '1,4p' "$RENDER_ERROR" >&2
+      rm -f "$RENDER_ERROR"
+      exit 5
     fi
   fi
+  rm -f "$RENDER_ERROR"
 fi
 
 if [ ! -f "$TMP_HTML" ]; then