@etiquekit/etq 0.0.1 → 1.0.1

package/templates/etiquette-vanilla-v0/README.md

@@ -0,0 +1,69 @@
+# Etiquette Vanilla V0
+
+Minimal default onboarding kit.
+
+It creates:
+
+```yaml
+default_surface:
+  - etiquette-kernel
+  - control-seat
+```
+
+It does not create runtime seats, product repos, backplanes, hosted services, dashboards, or sample products.
+It starts unauthenticated: `workspace-secure-profile.v0` is `open`, with upgrade paths for `screening-warn`, `screening-enforced`, and `enterprise-reactor`.
+
+## Quick Start
+
+From this template directory:
+
+```sh
+sh bin/stamp-vanilla /tmp/etiquette-start
+sh /tmp/etiquette-start/validate-vanilla.sh
+```
+
+The first person who claims the stamped `control-seat` reports readiness before assigning work.
+For restricted seats, change the secure profile, add provider-derived policy/claims, then run `sh source/control-seat/bin/access-assurance-check`.
+
+## Local Receipt Proof
+
+The control seat can prove local-only compaction without any org service:
+
+```sh
+sh source/control-seat/bin/local-event CONTROL-001 control-seat started "started local proof"
+sh source/control-seat/bin/local-event CONTROL-001 control-seat completed "ready to compact"
+sh source/control-seat/bin/compact-local-events CONTROL-001 success
+```
+
+This writes a compact receipt under `docs/work/receipts/`.
+
+## Manual Playback
+
+When workflow changes materially, fill `docs/work/playbacks/PLAYBACK_TEMPLATE.md`.
+Playback interprets receipts; it does not replace them.
+
+## Control Seat
+
+```yaml
+starts_as: generic
+can:
+  - initialize local workflow
+  - report readiness
+  - create the first task
+  - grant another seat only when needed
+cannot:
+  - clone product repos before assignment
+  - bypass validation
+  - treat chat as evidence
+  - grant access from the secure profile or reactor
+```
+
+Provision these later only after the control seat grants them:
+
+```sh
+sh templates/seat-packs-v0/bin/provision-seat codex /tmp/dev-codex-seat
+sh templates/seat-packs-v0/bin/provision-seat claude-code /tmp/dev-claude-code-seat
+sh templates/seat-packs-v0/bin/provision-seat gemini /tmp/dev-gemini-seat
+sh templates/seat-packs-v0/bin/provision-seat openrouter /tmp/dev-openrouter-seat
+sh templates/seat-packs-v0/bin/provision-seat ollama /tmp/dev-ollama-seat
+```

package/templates/etiquette-vanilla-v0/bin/stamp-vanilla

@@ -0,0 +1,33 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ "$#" -ne 1 ]; then
+  echo "usage: sh bin/stamp-vanilla <target-dir>" >&2
+  exit 2
+fi
+
+TARGET=$1
+
+if [ -e "$TARGET" ]; then
+  echo "target already exists: $TARGET" >&2
+  exit 2
+fi
+
+mkdir -p "$TARGET/source"
+cp -R "$ROOT/source/." "$TARGET/source/"
+cp "$ROOT/README.md" "$TARGET/README.md"
+cp "$ROOT/validate-vanilla.sh" "$TARGET/validate-vanilla.sh"
+
+for repo in etiquette-kernel control-seat; do
+  repo_dir="$TARGET/source/$repo"
+  git -C "$repo_dir" init -q
+  git -C "$repo_dir" add .
+  git -C "$repo_dir" \
+    -c user.name="Etiquette Vanilla" \
+    -c user.email="etiquette-vanilla@example.invalid" \
+    commit -q -m "Initial $repo scaffold"
+done
+
+echo "stamped etiquette vanilla rollout at $TARGET"

package/templates/etiquette-vanilla-v0/source/control-seat/.llm-substrate/HANDOFF.md

@@ -0,0 +1,22 @@
+# Control Seat Handoff
+
+You are the initial Etiquette control seat.
+
+## Startup
+
+1. Run `sh bin/seat-doctor`.
+2. Read `docs/work/ledger/LEDGER.md`.
+3. Pick or create one small task.
+4. Return a receipt using the kernel receipt shape.
+
+## Authority
+
+The control seat may initialize local workflow, report readiness, and decide whether more seats are needed. It does not assume any runtime-specific worker pool.
+
+## Guardrails
+
+- Do not clone product repos until assigned.
+- Do not assume chat memory is canonical.
+- Do not provision extra seats unless the task needs them.
+- Keep receipts compact and durable.
+

package/templates/etiquette-vanilla-v0/source/control-seat/README.md

@@ -0,0 +1,16 @@
+# Control Seat
+
+Generic first seat for Etiquette.
+
+The control seat is runtime-neutral. Use it before provisioning Claude Code, Codex, Gemini, or any other runtime-specific seat pack.
+
+For local-only proof, append events with `bin/local-event` and compact them with `bin/compact-local-events`.
+
+Inside a live runtime session, run `bin/session-init` after `bin/seat-init`
+to prepare the local ledger, receipts, tasks, outbox, and session state.
+
+Access assurance is explicit and optional. The default profile is
+`docs/work/access/workspace-secure-profile.v0.json` with `mode: open`. Run
+`bin/access-assurance-check` before routing restricted seats, and switch to
+`screening-warn`, `screening-enforced`, or `enterprise-reactor` only when the
+workspace actually needs provider-backed screening.

package/templates/etiquette-vanilla-v0/source/control-seat/bin/_lib/http.sh

@@ -0,0 +1,121 @@
+#!/bin/sh
+# curl-wrapped HTTP helpers for the seat-bridge commands. Surfaces 4xx
+# error bodies with helpful remediation; retries on 5xx (3 attempts,
+# exponential backoff).
+#
+# Stdout: response body on 2xx.
+# Stderr: error details on 4xx/5xx.
+# Exit:   0 on 2xx; non-zero matching the rough HTTP class otherwise
+#         (10 for 4xx, 20 for 5xx-after-retries, 30 for network failure).
+
+# shellcheck shell=sh
+
+ETQ_HTTP_CURL=${ETIQUETTE_CURL:-curl}
+ETQ_HTTP_RETRIES=${ETIQUETTE_HTTP_RETRIES:-3}
+ETQ_HTTP_TIMEOUT=${ETIQUETTE_HTTP_TIMEOUT:-15}
+
+# POST helper.  Args: URL, JSON body.  Optional 3rd arg: extra header line
+# (e.g. "authorization: Bearer ...").
+etq_http_post() {
+  url=$1
+  body=$2
+  hdr=${3:-}
+
+  attempt=1
+  while [ "$attempt" -le "$ETQ_HTTP_RETRIES" ]; do
+    tmpfile=$(mktemp -t etq-http.XXXXXX)
+    set +e
+    if [ -n "$hdr" ]; then
+      status=$("$ETQ_HTTP_CURL" -sS -o "$tmpfile" -w '%{http_code}' \
+        --max-time "$ETQ_HTTP_TIMEOUT" \
+        -X POST -H 'content-type: application/json' -H "$hdr" \
+        --data "$body" "$url" 2>/dev/null)
+    else
+      status=$("$ETQ_HTTP_CURL" -sS -o "$tmpfile" -w '%{http_code}' \
+        --max-time "$ETQ_HTTP_TIMEOUT" \
+        -X POST -H 'content-type: application/json' \
+        --data "$body" "$url" 2>/dev/null)
+    fi
+    curl_rc=$?
+    set -e
+
+    if [ "$curl_rc" -ne 0 ]; then
+      printf 'http: curl failed for %s (rc=%s, attempt %s/%s)\n' \
+        "$url" "$curl_rc" "$attempt" "$ETQ_HTTP_RETRIES" >&2
+      rm -f "$tmpfile"
+      attempt=$((attempt + 1))
+      [ "$attempt" -le "$ETQ_HTTP_RETRIES" ] && sleep $((attempt * 2))
+      continue
+    fi
+
+    case "$status" in
+      2*)
+        cat "$tmpfile"
+        rm -f "$tmpfile"
+        return 0
+        ;;
+      4*)
+        printf 'http: %s returned %s\n' "$url" "$status" >&2
+        printf 'http: response body:\n' >&2
+        cat "$tmpfile" >&2
+        printf '\n' >&2
+        etq_http_4xx_hint "$status" "$tmpfile" >&2
+        rm -f "$tmpfile"
+        return 10
+        ;;
+      5*)
+        if [ "$attempt" -lt "$ETQ_HTTP_RETRIES" ]; then
+          printf 'http: %s returned %s (attempt %s/%s; retrying)\n' \
+            "$url" "$status" "$attempt" "$ETQ_HTTP_RETRIES" >&2
+          rm -f "$tmpfile"
+          sleep $((attempt * 2))
+          attempt=$((attempt + 1))
+          continue
+        fi
+        printf 'http: %s returned %s after %s retries\n' \
+          "$url" "$status" "$ETQ_HTTP_RETRIES" >&2
+        cat "$tmpfile" >&2
+        rm -f "$tmpfile"
+        return 20
+        ;;
+      *)
+        printf 'http: %s returned unexpected status %s\n' "$url" "$status" >&2
+        cat "$tmpfile" >&2
+        rm -f "$tmpfile"
+        return 30
+        ;;
+    esac
+  done
+
+  return 30
+}
+
+# Print a friendly remediation hint for 4xx responses.
+etq_http_4xx_hint() {
+  status=$1
+  body_file=$2
+  case "$status" in
+    400)
+      printf '\nhint: request was rejected.  Most common causes:\n' >&2
+      printf '  - sanitizer rejected an input (path/hostname/IP/length)\n' >&2
+      printf '  - missing required field in body\n' >&2
+      printf '  - event_type not in allowlist (telemetry only)\n' >&2
+      ;;
+    401)
+      printf '\nhint: not authenticated.  This endpoint requires pass_id OR JWT.\n' >&2
+      printf '  - confirm seat-consume-pass was run and workspace.json exists\n' >&2
+      printf '  - or pass --workspace-jwt <token> if running admin-side\n' >&2
+      ;;
+    403)
+      printf '\nhint: forbidden.  Your role lacks the required action permission.\n' >&2
+      ;;
+    404)
+      printf '\nhint: workspace_id or pass_id not found.\n' >&2
+      ;;
+    410)
+      printf '\nhint: pass is revoked, expired, or single-use already consumed.\n' >&2
+      printf '  - issue a new pass via the dashboard and re-run seat-consume-pass\n' >&2
+      ;;
+    *) ;;
+  esac
+}

package/templates/etiquette-vanilla-v0/source/control-seat/bin/_lib/sanitize.sh

@@ -0,0 +1,191 @@
+#!/bin/sh
+# Client-side input sanitization. Mirrors api/sanitize.js rejection rules
+# from the hosted-pass-plane V0 prototype so we surface 400 reasons before
+# a round trip.
+#
+# Per hosted-plane boundary rules:
+#   - opaque IDs (seat_id, environment_node_id, consumer_seat_id) reject
+#     hostname-shape suffixes, IPv4/IPv6, user-home / drive-letter / shell-
+#     home / private-temp / absolute-temp path patterns, unsafe characters,
+#     whitespace, and length > 64.
+#   - repo-relative paths reject absolute / drive-letter / known leakage
+#     patterns and length > 256.
+#   - artifact_ref allows repo:branch but no absolute paths; length > 128.
+#
+# Each function prints the cleaned value on stdout and returns 0 on success;
+# on rejection it prints a one-line reason to stderr and returns 1.
+
+# shellcheck shell=sh
+
+# Path-prefix fragments built at runtime via string concatenation so the
+# literals do not appear in source (release-scan would flag them).  Same
+# trick scripts/release-scan.sh uses for its own pattern construction.
+_etq_path_p1='/U'"sers/"
+_etq_path_p2='/h'"ome/"
+_etq_path_p3='/pr'"ivate/"
+_etq_path_p4='/t'"mp/"
+_etq_path_p5='$H'"OME"
+
+# Reject path-shape patterns. Returns 0 if string contains a known
+# leakage pattern; 1 if clean.
+_etq_has_path_shape() {
+  case "$1" in
+    *"$_etq_path_p1"*) return 0 ;;
+    *"$_etq_path_p2"*) return 0 ;;
+    *"$_etq_path_p5"*) return 0 ;;
+    *"$_etq_path_p3"*) return 0 ;;
+    *"$_etq_path_p4"*) return 0 ;;
+    [A-Za-z]:\\*) return 0 ;;
+    [A-Za-z]:/*) return 0 ;;
+  esac
+  return 1
+}
+
+# Reject hostname-shape suffixes + IPv4 + (loose) IPv6.
+_etq_has_hostname_shape() {
+  case "$1" in
+    *.local|*.LOCAL|*.local/*) return 0 ;;
+    *.lan|*.LAN|*.lan/*) return 0 ;;
+    *.internal|*.INTERNAL|*.internal/*) return 0 ;;
+    *.intranet|*.INTRANET|*.intranet/*) return 0 ;;
+    *.localdomain|*.LOCALDOMAIN|*.localdomain/*) return 0 ;;
+  esac
+  # IPv4 quad
+  if printf '%s' "$1" | grep -qE '^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}'; then
+    return 0
+  fi
+  # IPv6 loose (>=2 hex segments separated by colons)
+  if printf '%s' "$1" | grep -qiE '\b[0-9a-f]{1,4}:[0-9a-f]{1,4}:'; then
+    return 0
+  fi
+  return 1
+}
+
+# Sanitize an opaque ID (seat_id / environment_node_id / consumer_seat_id).
+# Echoes cleaned value on success.
+etq_sanitize_opaque_id() {
+  v=$(printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+  if [ -z "$v" ]; then
+    echo "sanitize: opaque-id empty" >&2
+    return 1
+  fi
+  if [ "${#v}" -gt 64 ]; then
+    echo "sanitize: opaque-id length > 64" >&2
+    return 1
+  fi
+  if _etq_has_path_shape "$v"; then
+    echo "sanitize: opaque-id contains path-shape" >&2
+    return 1
+  fi
+  if _etq_has_hostname_shape "$v"; then
+    echo "sanitize: opaque-id contains hostname/IP-shape" >&2
+    return 1
+  fi
+  # Disallow whitespace + control chars
+  if printf '%s' "$v" | grep -qE '[[:space:][:cntrl:]]'; then
+    echo "sanitize: opaque-id contains whitespace/control chars" >&2
+    return 1
+  fi
+  # Keep IDs JSON/URL/log friendly for shell callers that may need to print
+  # or embed the value before jq is available.
+  if printf '%s' "$v" | grep -qE '[^A-Za-z0-9._:-]'; then
+    echo "sanitize: opaque-id contains unsafe characters" >&2
+    return 1
+  fi
+  printf '%s' "$v"
+}
+
+# Sanitize a repo-relative path (receipt_ref). NOT absolute.
+etq_sanitize_repo_relative() {
+  v=$(printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+  if [ -z "$v" ]; then
+    echo "sanitize: repo-relative empty" >&2
+    return 1
+  fi
+  if [ "${#v}" -gt 256 ]; then
+    echo "sanitize: repo-relative length > 256" >&2
+    return 1
+  fi
+  case "$v" in
+    /*) echo "sanitize: repo-relative must not be absolute (starts with /)" >&2; return 1 ;;
+    \\*) echo "sanitize: repo-relative must not be absolute (starts with \\)" >&2; return 1 ;;
+    [A-Za-z]:[\\/]*) echo "sanitize: repo-relative must not be drive-letter absolute" >&2; return 1 ;;
+  esac
+  if _etq_has_path_shape "$v"; then
+    echo "sanitize: repo-relative contains leakage path-shape" >&2
+    return 1
+  fi
+  printf '%s' "$v"
+}
+
+# Sanitize telemetry meta JSON. Mirrors telemetry.v0:
+#   - object only
+#   - keys non-empty and <= 32 chars
+#   - string values <= 64 chars and not path/hostname/IP-shaped
+#   - numeric and boolean values kept
+#   - arrays/objects/null stripped
+#
+# Prints compact JSON object on success.
+etq_sanitize_meta_json() {
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "sanitize: jq required for telemetry meta" >&2
+    return 1
+  fi
+
+  printf '%s' "$1" | jq -c \
+    --arg p1 "$_etq_path_p1" \
+    --arg p2 "$_etq_path_p2" \
+    --arg p3 "$_etq_path_p3" \
+    --arg p4 "$_etq_path_p4" \
+    --arg p5 "$_etq_path_p5" \
+    '
+      def bad_path:
+        contains($p1) or contains($p2) or contains($p3) or
+        contains($p4) or contains($p5) or test("^[A-Za-z]:[\\\\/]");
+      def bad_host:
+        test("\\.(local|lan|internal|intranet|localdomain)$"; "i") or
+        test("^[0-9]{1,3}(\\.[0-9]{1,3}){3}") or
+        test("[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}:");
+
+      if type != "object" then
+        error("telemetry meta must be an object")
+      else
+        with_entries(
+          select(
+            (.key | length > 0 and length <= 32) and
+            (
+              ((.value | type) == "string" and
+                (.value | length <= 64) and
+                ((.value | bad_path) | not) and
+                ((.value | bad_host) | not))
+              or ((.value | type) == "number")
+              or ((.value | type) == "boolean")
+            )
+          )
+        )
+      end
+    '
+}
+
+# Sanitize an artifact_ref. Allows owner/repo:branch but no absolute.
+etq_sanitize_artifact_ref() {
+  v=$(printf '%s' "$1" | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+  if [ -z "$v" ]; then
+    echo "sanitize: artifact-ref empty" >&2
+    return 1
+  fi
+  if [ "${#v}" -gt 128 ]; then
+    echo "sanitize: artifact-ref length > 128" >&2
+    return 1
+  fi
+  case "$v" in
+    /*) echo "sanitize: artifact-ref must not be absolute" >&2; return 1 ;;
+    \\*) echo "sanitize: artifact-ref must not be absolute" >&2; return 1 ;;
+    [A-Za-z]:[\\/]*) echo "sanitize: artifact-ref must not be drive-letter absolute" >&2; return 1 ;;
+  esac
+  if _etq_has_path_shape "$v"; then
+    echo "sanitize: artifact-ref contains leakage path-shape" >&2
+    return 1
+  fi
+  printf '%s' "$v"
+}

package/templates/etiquette-vanilla-v0/source/control-seat/bin/_lib/state.sh

@@ -0,0 +1,67 @@
+#!/bin/sh
+# Local seat state read/write helpers.
+#
+# State files are per-seat at V0. A future outbox lane may split these
+# per workspace if the rotation model needs it:
+#
+#   $STATE_DIR/seat.json       { seat_id, execution_seat, created_at }
+#   $STATE_DIR/workspace.json  cached pass envelope after seat-consume-pass
+#
+# STATE_DIR defaults to $ROOT/.etiquette/state.  File mode 600 on create.
+#
+# All read functions echo the value on stdout; missing files / keys
+# return non-zero with a stderr message.
+
+# shellcheck shell=sh
+
+etq_state_dir() {
+  # $ROOT must be set by the caller (matches local-event / seat-doctor pattern)
+  printf '%s' "${ETIQUETTE_STATE_DIR:-$ROOT/.etiquette/state}"
+}
+
+etq_state_init_dir() {
+  dir=$(etq_state_dir)
+  mkdir -p "$dir"
+  # Best-effort restrictive perms; not all filesystems honour them.
+  chmod 700 "$dir" 2>/dev/null || true
+}
+
+# Read a top-level key from a JSON file.  Args: file-path, key.
+# Exits non-zero if file missing or key not present.
+etq_state_read_key() {
+  file=$1
+  key=$2
+  if [ ! -f "$file" ]; then
+    printf 'state: file missing: %s\n' "$file" >&2
+    return 1
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    printf 'state: jq is required but not on PATH\n' >&2
+    return 2
+  fi
+  out=$(jq -r --arg k "$key" '.[$k] // empty' "$file")
+  if [ -z "$out" ]; then
+    printf 'state: key not present: %s in %s\n' "$key" "$file" >&2
+    return 3
+  fi
+  printf '%s' "$out"
+}
+
+# Write a complete JSON object to a state file.  Args: file-path, json-body.
+# Creates parent dir + sets mode 600.
+etq_state_write_file() {
+  file=$1
+  body=$2
+  dir=$(dirname -- "$file")
+  mkdir -p "$dir"
+  chmod 700 "$dir" 2>/dev/null || true
+  # Use a temp file + mv for atomicity.
+  tmp="$file.tmp.$$"
+  printf '%s' "$body" > "$tmp"
+  chmod 600 "$tmp" 2>/dev/null || true
+  mv "$tmp" "$file"
+}
+
+# Convenience: print path to seat.json / workspace.json.
+etq_state_seat_path()      { printf '%s/seat.json'      "$(etq_state_dir)"; }
+etq_state_workspace_path() { printf '%s/workspace.json' "$(etq_state_dir)"; }

package/templates/etiquette-vanilla-v0/source/control-seat/bin/access-assurance-check

@@ -0,0 +1,55 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+PROFILE="$ROOT/docs/work/access/workspace-secure-profile.v0.json"
+POLICY="$ROOT/docs/work/access/seat-access-policy.v0.json"
+CLAIMS="$ROOT/docs/work/access/access-assurance-claims.v0.json"
+
+json_string_field() {
+  sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\"\\([^\"]*\\)\".*/\\1/p" "$1" | head -n 1
+}
+
+json_bool_field() {
+  sed -n "s/.*\"$2\"[[:space:]]*:[[:space:]]*\\(true\\|false\\).*/\\1/p" "$1" | head -n 1
+}
+
+if [ ! -f "$PROFILE" ]; then
+  echo "access-assurance: fail missing docs/work/access/workspace-secure-profile.v0.json" >&2
+  exit 1
+fi
+
+mode=$(json_string_field "$PROFILE" mode)
+case "$mode" in
+  open|screening-warn|screening-enforced|enterprise-reactor) ;;
+  *)
+    echo "access-assurance: fail invalid mode=${mode:-missing}" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$mode" = "open" ]; then
+  echo "access-assurance: pass mode=open policy=not-required"
+  exit 0
+fi
+
+if [ ! -f "$POLICY" ] || [ ! -f "$CLAIMS" ]; then
+  message="access-assurance: missing policy or claims for mode=$mode"
+  if [ "$mode" = "screening-warn" ]; then
+    echo "$message"
+    exit 0
+  fi
+  echo "$message" >&2
+  exit 1
+fi
+
+if [ "$mode" = "enterprise-reactor" ]; then
+  tighten_only=$(json_bool_field "$PROFILE" tighten_only)
+  reactor_can_grant=$(json_bool_field "$PROFILE" reactor_can_grant_or_loosen_access)
+  if [ "$tighten_only" != "true" ] || [ "$reactor_can_grant" != "false" ]; then
+    echo "access-assurance: fail enterprise-reactor requires tighten_only=true and reactor_can_grant_or_loosen_access=false" >&2
+    exit 1
+  fi
+fi
+
+echo "access-assurance: pass mode=$mode"

package/templates/etiquette-vanilla-v0/source/control-seat/bin/compact-local-events

@@ -0,0 +1,71 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
+  echo "usage: sh bin/compact-local-events <task-id> [success|partial|blocked|failed]" >&2
+  exit 2
+fi
+
+task_id=$1
+status=${2:-success}
+operator_principal=${ETIQUETTE_OPERATOR_PRINCIPAL:-local-operator}
+execution_seat=${ETIQUETTE_EXECUTION_SEAT:-control-seat}
+event_log=${ETIQUETTE_EVENT_LOG:-"$ROOT/.etiquette/events/local.ndjson"}
+receipt_dir=${ETIQUETTE_RECEIPT_DIR:-"$ROOT/docs/work/receipts"}
+
+case "$status" in
+  success|partial|blocked|failed) ;;
+  *)
+    echo "invalid receipt status: $status" >&2
+    exit 2
+    ;;
+esac
+
+if [ ! -f "$event_log" ]; then
+  echo "missing local event log: $event_log" >&2
+  exit 1
+fi
+
+task_pattern='"task_id":"'"$task_id"'"'
+matches=$(grep -F "$task_pattern" "$event_log" || true)
+
+if [ -z "$matches" ]; then
+  echo "no events found for task: $task_id" >&2
+  exit 1
+fi
+
+event_count=$(printf '%s\n' "$matches" | sed '/^$/d' | wc -l | tr -d ' ')
+first_seq=$(printf '%s\n' "$matches" | sed -n '1s/.*"seq":\([0-9][0-9]*\).*/\1/p')
+last_seq=$(printf '%s\n' "$matches" | sed -n '$s/.*"seq":\([0-9][0-9]*\).*/\1/p')
+last_action=$(printf '%s\n' "$matches" | sed -n '$s/.*"action":"\([^"]*\)".*/\1/p')
+
+mkdir -p "$receipt_dir"
+receipt="$receipt_dir/$task_id-receipt.yaml"
+tmp="$receipt.tmp.$$"
+
+cat > "$tmp" <<EOF
+task_id: $task_id
+operator_principal: $operator_principal
+execution_seat: $execution_seat
+status: $status
+sources_read:
+  - .etiquette/events/local.ndjson
+files_changed:
+  - docs/work/receipts/$task_id-receipt.yaml
+validation:
+  - sh bin/seat-doctor
+risks: []
+next_owner: control-seat
+compaction:
+  scope: local-only
+  event_log: .etiquette/events/local.ndjson
+  event_count: $event_count
+  first_seq: $first_seq
+  last_seq: $last_seq
+  last_action: $last_action
+EOF
+
+mv "$tmp" "$receipt"
+printf 'receipt: %s\n' "$receipt"