create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/.claude/settings.json

@@ -0,0 +1,131 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash",
+      "Read",
+      "Write",
+      "Edit"
+    ],
+    "deny": [
+      "Edit(~/.egregore/instances.json)"
+    ],
+    "additionalDirectories": [
+      "memory"
+    ]
+  },
+  "defaultMode": "acceptEdits",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/memory-refresh.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/emissary-detect.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/observe-context.sh claude",
+            "timeout": 45
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Edit|Write|Bash|Glob|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/boundary-check.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|Bash|EnterWorktree|EnterPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/onboarding-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|Bash|EnterPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/branch-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/retrieval-context.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/card-context.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeCreate": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/worktree-create.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/worktree-remove.sh"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/bin/session-log.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "\"$CLAUDE_PROJECT_DIR\"/bin/statusline.sh"
+  }
+}

package/runtime/claude/.claude/skills/activity/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: activity
+description: "Explicit Activity card only. Use when the user names /activity or directly asks to show, open, or render the Activity dashboard/card. Never use it to answer or synthesize what the team is focused on, busy with, prioritizing, or doing; analytical organizational questions use Search/Runtime QMD."
+---
+
+# Activity
+
+Use this bounded status card only when the user names Activity or directly asks
+to display its dashboard/card. "Explicit" means display intent, not merely a
+question about the team. Questions asking for explanation or synthesis of
+current focus, themes, priorities, or work use attached
+`EGREGORE_ORG_CONTEXT_V1` evidence or exactly one Search workflow query when
+that evidence is absent. The same applies to returning to earlier work. Never
+use Activity as discovery or analysis fallback.
+
+Render the team view immediately. The renderer's stdout IS the product card:
+fully visible the moment rendering finishes, appearing exactly once in the
+conversation. Never copy, regenerate, summarize, or repeat the
+card — or any of its rows — in your reply. The card's own closing question is
+the prompt for the next turn; after the command, add nothing beyond an
+answer to something the user separately asked.
+
+## When to invoke
+
+Explicit Activity card only. Use when the user names /activity or directly asks to show, open, or render the Activity dashboard/card. Never use it to answer or synthesize what the team is focused on, busy with, prioritizing, or doing; analytical organizational questions use Search/Runtime QMD.
+
+## Read path
+
+Fetch exactly one authorized Runtime snapshot and render it:
+
+```bash
+bash bin/activity-data.sh 2>/dev/null \
+  | bash bin/node-run.sh bin/codex-skill-render.mjs activity-card -
+```
+
+Do not sync repositories, query memory again, or call implementation
+infrastructure directly. The snapshot already contains bounded
+canonical sessions, questions, quests, todos, and lifecycle-resolved handoffs.
+Canonical Markdown/Git wins over every projection.
+
+Connected enrichment is a separate capability-authorized adapter. Use it only
+when the user explicitly asks for Connected/projected status by setting
+`EGREGORE_STATUS_CONNECTED_ENRICH=1` for the same single data command. Never
+replace canonical lifecycle fields with the returned projection payload.
+
+## Handoff actions
+
+For `activity done N`, `activity expire N`, or `activity reopen N`:
+
+1. Fetch one snapshot as above.
+2. Map `N` to `handoffs_to_me[N-1]`.
+3. Run one typed transition:
+
+```bash
+bash bin/activity-action.sh <done|expire|reopen> "<sessionId>" \
+  --expected-revision "<lifecycleRevision>"
+```
+
+Report the resulting canonical state. Never accept graph state as lifecycle
+authority, silently complete work by age, or record focus through graph calls.
+
+## Rendering rules
+
+- Never print raw JSON or narrate routine commands.
+- Preserve the shared 72-column activity card.
+- Show Local status without graph/setup messaging.
+- End the turn after the card; act on the user's reply next turn.
+- Use `/activity quests` to show the snapshot's full bounded quest list.

package/runtime/claude/.claude/skills/announce/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: announce
+description: "Draft, preview, and explicitly send an Egregore group announcement. Use for /announce, telling the team something, or notifying everyone—not a direct message or structured handoff."
+---
+
+# Egregore announce
+
+Draft one concise group message. The request authorizes drafting, never
+dispatch or artifact publication. Reuse sufficient `EGREGORE_ORG_CONTEXT_V1`;
+do not repeat organizational retrieval merely to decorate the message.
+
+Preserve quoted wording exactly. Otherwise use 2–5 lines: what changed, the
+relevant branch/artifact when already authorized, and the requested action.
+Notification consent and publication consent are separate. Never publish a
+referenced artifact automatically; publication is a separate
+`SHARE` workflow with its own source/destination approval.
+
+Write the final draft to a private temporary file and prepare one actor-bound
+Runtime plan:
+
+```bash
+MESSAGE_FILE="$(mktemp "${TMPDIR:-/tmp}/egregore-announce.XXXXXX")"
+chmod 600 "$MESSAGE_FILE"
+printf '%s' "$MESSAGE" > "$MESSAGE_FILE"
+PLAN_JSON=$(bash bin/notification.sh plan --kind group --message-file "$MESSAGE_FILE")
+rm -f "$MESSAGE_FILE"
+```
+
+Show one dedicated **Send / Edit / Cancel** checkpoint containing the exact
+organization, group, every delivery/channel, and final message returned by the
+plan. Edit cancels the old plan before creating a new one. Cancel calls:
+
+```bash
+bash bin/notification.sh cancel "$PLAN_ID"
+```
+
+Only a fresh **Send** response for that exact checkpoint authorizes:
+
+```bash
+APPROVAL_JSON=$(bash bin/notification.sh approve \
+  "$PLAN_ID" "$DIGEST" APPROVE_EXACT_NOTIFICATION)
+APPROVAL_TOKEN=$(printf '%s' "$APPROVAL_JSON" | jq -r '.approval_token')
+bash bin/notification.sh dispatch "$PLAN_ID" "$APPROVAL_TOKEN"
+```
+
+Report the returned delivery receipt. Never retry from old approval, change a
+destination, or fall back to another channel. Local instances without a
+notification capability stop after preview and return the text for manual use.
+The Runtime service owns ActorContext authorization, exact-plan binding,
+transport, and content-free telemetry.
+
+## When to invoke
+
+Draft, preview, and explicitly send an Egregore group announcement. Use for /announce, telling the team something, or notifying everyone—not a direct message or structured handoff.

package/runtime/claude/.claude/skills/archive/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: archive
+description: "Capture an effective prompting or steering technique as a reusable canonical pattern. Use when a prompt chain worked especially well; use /reflect for insight about the work and /note for a private thought."
+---
+
+# Archive
+
+Capture a reusable human-to-agent steering technique as a typed `pattern` with
+subtype `prompt-chain`.
+
+## When to invoke
+
+Capture an effective prompting or steering technique as a reusable canonical pattern. Use when a prompt chain worked especially well; use /reflect for insight about the work and /note for a private thought.
+
+## Modes
+
+- No arguments: inspect this session for a meaningful steering chain. If the
+  session is too short or no chain exists, ask the user to describe one.
+- Arguments: treat them as the technique; a single principle is a one-move
+  chain.
+
+Each move records its type, trigger, intervention, effect, and distilled
+principle. Useful initial move types include inversion, calibration, scoping,
+elevation, reframing, grounding, sequencing, contradiction, analogy, and
+provocation; extend the vocabulary when needed.
+
+## Context and dedupe
+
+Reuse attached `EGREGORE_ORG_CONTEXT_V1` evidence. Do not repeat retrieval when
+it already contains sufficient related patterns. If a named gap remains, make
+one `bash bin/search.sh query "<technique concept>" -n 6` call and open only a
+likely duplicate through `bash bin/search.sh open`. Never query implementation
+infrastructure or storage directly.
+
+## Flow
+
+1. Extract a chain name, when-to-use guidance, ordered moves, outcome, topics,
+   workstream, and explicit relations.
+2. For a three-or-more move chain, show the complete breakdown. For shorter
+   chains, show the compact proposal. Wait for `y`, edits, or `skip`.
+3. Render the accepted pattern body to a temporary file and invoke exactly one
+   canonical command:
+
+```bash
+bash bin/knowledge.sh create \
+  --type pattern \
+  --subtype prompt-chain \
+  --title "{chain name}" \
+  --input "$TMP_ARTIFACT" \
+  --topic prompt-chain \
+  --topic "{topic}" \
+  --workstream "{workstream}"
+```
+
+Add `--relationship "RELATION:TARGET"` only for explicit links. The Runtime
+resolves ActorContext, authorizes, assigns stable identity/provenance, persists
+canonical Markdown, records Git provenance, refreshes retrieval, starts
+background embedding, and emits content-free telemetry.
+
+## Boundaries
+
+- Archive captures an AI-steering technique, not a work decision or private
+  scratch thought.
+- Do not separately run `/save`, Git, QMD, graph, telemetry, publishing,
+  sharing, or notifications.
+- Graph projection is optional and advisory. Canonical Markdown wins.
+- Publishing, external sharing, or notification requires a separate permitted,
+  explicitly consented action.
+
+Report the canonical path and writeback status. Preserve the compact
+`◇ ARCHIVE` confirmation style for rich output.

package/runtime/claude/.claude/skills/branch/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: branch
+description: "Create a working branch from what you are about to work on. Use for /branch, or any request to start a new branch before making changes."
+---
+
+Create a working branch from what you're working on.
+
+## When to invoke
+
+User says: "/branch", "create a branch", "start a new branch", or any request to begin a working branch for what they're about to do
+
+Description: $ARGUMENTS
+
+## What to do
+
+Resolve the core repo's configured base first:
+```bash
+BASE_BRANCH=$(bash -c 'SCRIPT_DIR="$PWD"; CONFIG="$PWD/egregore.json"; . "$PWD/bin/lib/config.sh" && _get_base_branch') ||
+  { echo "Could not resolve the configured base branch; stopping before Git changes." >&2; exit 1; }
+```
+
+1. Derive a topic slug from the description (lowercase, hyphens, no special chars, max 40 chars)
+2. Determine branch type from description:
+   - `dev/{author}/{topic-slug}` — default for session work
+   - `feature/{topic-slug}` — explicit feature work
+   - `bugfix/{topic-slug}` — bug fixes
+3. Call `EnterWorktree` with `name` set to the topic slug
+
+The WorktreeCreate hook handles everything: fetches the configured base branch, creates the branch, creates the worktree, sets up symlinks.
+
+**Fallback:** If `EnterWorktree` fails, fall back to: `git checkout --no-track -b {branch-name} "origin/$BASE_BRANCH"`
+
+The task branch must not inherit `origin/$BASE_BRANCH` as its upstream. The
+first `/push` sets upstream with `-u origin "$BRANCH"`, creating and tracking
+the same-name remote task branch.
+
+## Deriving the topic slug
+
+Extract the essence of what the user said into a short, meaningful slug:
+- "auth flow in frontend" → `auth-flow`
+- "fix the payment endpoint bug" → `fix-payment-endpoint`
+- "refactoring the token store" → `refactor-token-store`
+- "working on oauth implementation" → `oauth-implementation`
+
+If no description is given, use today's date: `YYYY-MM-DD`
+
+## Branch type detection
+
+- Description mentions "fix", "bug", "broken", "crash" → `bugfix/`
+- Description mentions "feature", "add", "implement", "new" → `feature/`
+- Otherwise → `dev/{author}/` (general session work)
+
+## Resuming existing branches
+
+Before creating, check if a matching branch already exists:
+```bash
+git branch --list "dev/$AUTHOR/*$SLUG*" "feature/*$SLUG*" "bugfix/*$SLUG*"
+```
+
+If a match is found, offer to resume it instead of creating a new one.
+
+## Reusing current worktree
+
+If already in a worktree and the user needs a new branch (e.g., after their PR was merged):
+1. Do NOT exit the worktree or create a new one
+2. Create the new branch and checkout within the existing worktree:
+   ```bash
+   git fetch origin "$BASE_BRANCH" --quiet
+   git checkout --no-track -b dev/$AUTHOR/$NEW_SLUG "origin/$BASE_BRANCH"
+   ```
+3. The worktree directory stays the same — only the branch changes
+4. Confirm: `Switched to dev/$AUTHOR/$NEW_SLUG (same worktree).`
+
+## Example
+
+```
+> /branch auth flow
+
+Creating branch...
+
+  git fetch origin "$BASE_BRANCH" --quiet
+  git branch dev/alice/auth-flow "origin/$BASE_BRANCH"
+  EnterWorktree → .claude/worktrees/auth-flow/
+  git checkout dev/alice/auth-flow
+  bash <main-dir>/bin/worktree.sh setup "$(pwd)" "<main-dir>"
+  ✓ Created dev/alice/auth-flow (worktree, from configured base)
+
+Ready to work. /save when done.
+```
+
+```
+> /branch fix payment endpoint bug
+
+Creating branch...
+
+  git fetch origin "$BASE_BRANCH" --quiet
+  git branch bugfix/fix-payment-endpoint "origin/$BASE_BRANCH"
+  EnterWorktree → .claude/worktrees/fix-payment-endpoint/
+  git checkout bugfix/fix-payment-endpoint
+  ✓ Created bugfix/fix-payment-endpoint (worktree, from configured base)
+
+Ready to work. /save when done.
+```
+
+```
+> /branch
+
+No description given. Using today's date.
+
+  git branch dev/alice/2026-02-12 "origin/$BASE_BRANCH"
+  EnterWorktree → .claude/worktrees/2026-02-12/
+  git checkout dev/alice/2026-02-12
+  ✓ Created dev/alice/2026-02-12 (worktree, from configured base)
+
+Ready to work. /save when done.
+```
+
+## Managed repos
+
+If the user's description references a managed repo (listed in `egregore.json` → `repos[]`), create the branch in that repo's sibling directory instead of the hub.
+
+Resolve the repo's base branch first:
+```bash
+BASE_BRANCH=$(bash -c 'SCRIPT_DIR="$PWD"; CONFIG="$PWD/egregore.json"; . "$PWD/bin/lib/config.sh" && _get_base_branch "$1"' _ "$REPO") ||
+  { echo "Could not resolve the configured base branch; stopping before Git changes." >&2; exit 1; }
+REPO_DIR="$(cd .. && pwd)/$REPO"
+git -C "$REPO_DIR" fetch origin "$BASE_BRANCH" --quiet
+git -C "$REPO_DIR" checkout --no-track -b dev/$AUTHOR/$TOPIC_SLUG "origin/$BASE_BRANCH"
+```
+
+Use `git -C` with absolute paths — never `cd` into the repo.
+
+```
+> /branch auth flow in frontend
+
+Creating branch in frontend...
+
+  git -C ../frontend fetch origin main --quiet
+  git -C ../frontend checkout --no-track -b dev/alice/auth-flow origin/main
+  ✓ Created dev/alice/auth-flow in frontend (from main)
+
+Ready to work. /save when done.
+```
+
+## Next
+
+Make your changes, then `/commit` or `/save` when ready.

package/runtime/claude/.claude/skills/checkup/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: checkup
+description: "Run diagnostics on an Egregore environment and render a health report, repairing safe local Runtime problems when possible. Use for /checkup, a health check, or when something is broken and the root cause is unclear."
+---
+
+# Egregore checkup
+
+Diagnose the Egregore Runtime first. Treat canonical Markdown and its
+instance-owned Local Retriever as the product baseline. Graph, control-plane,
+and notification probes are explicit Connected integrations; their failure
+must never make canonical Local Runtime state look unavailable.
+
+## When to invoke
+
+Run diagnostics on an Egregore environment and render a health report, repairing safe local Runtime problems when possible. Use for /checkup, a health check, or when something is broken and the root cause is unclear.
+
+## Procedure
+
+Detect mode without attempting a network call:
+
+```bash
+MODE=$(jq -r '.mode // empty' egregore.json 2>/dev/null)
+API_URL=$(jq -r '.api_url // empty' egregore.json 2>/dev/null)
+if [ "$MODE" = "local" ] || [ -z "$API_URL" ]; then
+  MODE="local"
+else
+  MODE="connected"
+fi
+```
+
+Run three sequential batches. Parallelize only within a batch.
+
+1. Runtime and local configuration.
+2. Connected integrations, only when `MODE=connected`.
+3. Workspace and Git checks.
+
+Never run Connected network probes beside local checks; a timeout must not
+cancel or obscure the Runtime result.
+
+## Batch 1: canonical Runtime
+
+Read the one typed Runtime health surface as JSON:
+
+```bash
+EGREGORE_ROOT="$PWD" PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" \
+  python3 -m egregore_runtime.harness_cli status --json
+```
+
+Do not invoke `qmd`, inspect QMD process tables, guess ports, or read another
+instance's runtime directory. The adapter owns those mechanics. Interpret the
+returned fields as follows:
+
+- `canonical_state_ready` — foundational. Fail only when canonical memory is
+  unavailable.
+- `adapter=qmd-local`, `collection`, and `index_path` — the resolved
+  instance-owned Local Retriever. Display these without exposing another
+  instance or deriving ownership yourself.
+- `runtime_state`, `runtime_pid`, and `runtime_endpoint` — owned worker
+  readiness. `semantic_ready` is healthy; `semantic_index_building` is a
+  warning with lexical fallback; `runtime_unavailable` is repairable.
+- `bm25_ready` — local keyword readiness. Warn when false.
+- `semantic_ready` and `embedding_state` — semantic readiness. A warming or
+  missing model is degraded, not canonical data loss.
+- `index_spec_version`, `index_revision`, and `source_revision` — freshness.
+  Report drift; never repair it by editing index files.
+- `warnings` — show concise, redacted messages.
+
+Also validate `egregore.json`, the canonical `memory` link/repository, and the
+mode-appropriate key names in `.env`. Never print secret values. Local mode
+requires no control-plane key.
+
+If the Runtime worker or indexes are unavailable while canonical memory is
+ready, run the safe Runtime lifecycle adapter once:
+
+```bash
+bash bin/search.sh start
+```
+
+Then re-read Runtime health once. This starts or reuses only the worker owned
+by this Egregore instance and schedules semantic warming behind the adapter.
+
+## Batch 2: Connected integrations
+
+Skip this batch completely in local mode. In connected mode, label every row
+as an integration, keep it outside the foundational Runtime verdict, and run:
+
+```bash
+timeout 10 bash bin/graph-projection.sh verify --enable 2>&1; echo "EXIT:$?"
+timeout 10 bash bin/notification.sh status 2>&1; echo "EXIT:$?"
+```
+
+- **Control plane / Graph projection** — pass when the gateway accepts the
+  configured credentials and the projection is reachable. Offline, auth, or
+  stale projection results are Connected warnings; canonical Markdown remains
+  authoritative.
+- **Notification adapter** — read the sanitized Runtime `status` field. Treat
+  `ok` (connected) or `configured` (local) as healthy. Telegram is optional
+  and never part of Runtime readiness.
+
+Do not auto-replace API keys, repair graph state, publish, or send a
+notification. Report the exact integration boundary that failed.
+
+## Batch 3: workspace
+
+Check locally:
+
+- the configured base branch exists and compare it with `origin/<base>` only
+  when an origin is already configured;
+- the current worktree and memory repository are clean or clearly report their
+  dirty-file counts;
+- the framework version is readable locally. Do not fetch merely to render a
+  health report;
+- the shell launcher points at this instance when a launcher is configured.
+
+Never mutate Git, canonical memory, or framework files during diagnosis.
+Offer `$pull`, `$update`, or `$setup` as the next Egregore action when relevant;
+do not tell the user to construct repair commands manually.
+
+## Rendering
+
+Render one compact diagnostic box. In connected mode add a separate
+`CONNECTED INTEGRATIONS` section after `RUNTIME`; in local mode omit it.
+
+```text
+┌──────────────────────────────────────────────────────────────────────┐
+│  ⊕ CHECKUP                                          {date}         │
+├──────────────────────────────────────────────────────────────────────┤
+│  CONFIG                                                              │
+│  ✓ Instance — {org} ({mode})                                        │
+│                                                                      │
+│  RUNTIME                                                             │
+│  ✓ Canonical memory — ready · source {source_revision}              │
+│  ✓ Local Retriever — qmd-local {adapter_version} · owned            │
+│  ⚠ Semantic index — warming · lexical fallback ready                │
+│  ✓ Worker — pid {pid} · {endpoint}                                  │
+│                                                                      │
+│  CONNECTED INTEGRATIONS                                              │
+│  ⚠ Control plane / Graph — offline · canonical state unaffected     │
+│  ✓ Telegram — connected                                             │
+│                                                                      │
+│  WORKSPACE                                                           │
+│  ✓ Memory repository — clean                                        │
+│  ✓ Git — {base} synced                                               │
+├──────────────────────────────────────────────────────────────────────┤
+│  Runtime ready · {warnings} warnings · integrations {state}         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+Use `✓`, `⚠`, and `✗` for pass, degraded, and unavailable. State the Runtime
+verdict independently from Connected integration health. After a safe Runtime
+repair, append only the rechecked result.
+
+## Rules
+
+- Never expose raw JSON, tokens, environment values, or unformatted probes.
+- Never use Graph or a control-plane response as canonical health authority.
+- Never call QMD directly; instance ownership belongs to Egregore Runtime.
+- Never send, publish, commit, pull, or push as part of checkup.
+- Emit telemetry only through the normal command wrapper, best-effort.