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

package/runtime/claude/.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: review-pr
+description: "Use when the user says 'review PR', 'is this PR safe to merge', or 'audit PR' — runs a CTO-level 10-point review checklist on one or more pull requests. Not creating a PR (/pr) or validating local changes (/test)."
+---
+
+Review a pull request with CTO-level scrutiny. Designed for vibe-coded PRs.
+
+Arguments: $ARGUMENTS
+
+## When to invoke
+
+User says: "review PR", "check this PR", "review #123", "is this PR safe to merge", "audit PR", "review cem's PRs"
+Not this: "/pr" (create a PR), "/test" (validate local changes)
+
+## Execution rules
+
+**CRITICAL: Suppress raw output.** Never show raw JSON, raw diffs, or unformatted gh output. All output should be structured assessment.
+
+**Use Agent tool for diff review.** Each PR gets its own background agent for parallel analysis. The agent fetches the diff, analyzes it, and returns a structured verdict.
+
+**Auth:** All `gh` commands need: `GITHUB_TOKEN=$(grep '^GITHUB_TOKEN=' .env | cut -d'=' -f2-)`
+
+## Step 0: Determine scope
+
+Parse `$ARGUMENTS`:
+- **PR number** (e.g. `123`, `#123`) → review that single PR
+- **Author** (e.g. `alice`, `bob`) → list all open PRs from that author
+- **`--all`** → list all open PRs
+- **Empty** → list all open PRs targeting develop
+
+Get org/repo:
+```bash
+GITHUB_ORG=$(jq -r '.github_org' egregore.json)
+REPO_NAME=$(jq -r '.repo_name // "egregore"' egregore.json)
+```
+
+## Step 1: Fetch PR metadata
+
+### Single PR
+```bash
+GITHUB_TOKEN=$TOKEN gh pr view $PR_NUM --json title,author,additions,deletions,changedFiles,headRefName,body,createdAt,state --repo $GITHUB_ORG/$REPO_NAME
+```
+
+### Multiple PRs (author or --all)
+```bash
+GITHUB_TOKEN=$TOKEN gh pr list --state open --json number,title,author,additions,deletions,changedFiles,headRefName,createdAt --limit 50 --repo $GITHUB_ORG/$REPO_NAME
+```
+
+Filter by author login if specified.
+
+## Step 2: For each PR, run the 10-point checklist
+
+Launch an Agent (subagent_type: general-purpose) per PR for parallel review. Give each agent:
+1. The PR number
+2. The repo
+3. The GITHUB_TOKEN retrieval command
+4. The full checklist below
+
+### The 10-Point CTO Checklist
+
+Each agent must fetch the diff (`gh pr diff $PR_NUM`) and evaluate:
+
+#### 1. Does it actually work?
+- Check that all imports reference functions/modules that exist
+- Check that Cypher syntax is valid (balanced parentheses, proper MATCH/RETURN/WHERE structure)
+- Check that shell scripts use correct flags for the target platform (e.g. `base64 -d` vs `-D` on macOS)
+- Check that referenced files/scripts actually exist in the codebase (e.g. `bin/graph-batch.sh`, `bin/graph-op.sh`)
+
+#### 2. Side effects on shared state
+- Does it modify `.claude/settings.json`? (hook changes affect every session)
+- Does it modify `CLAUDE.md`? (behavioral changes affect every session)
+- Does it modify `bin/graph-op.sh`? (new operations must not break existing ones)
+- Does it modify `bin/session-start.sh`? (startup changes affect every session)
+- Does it modify `.env`, `egregore.json`, or auth flows?
+
+#### 3. Overlap detection
+- Are there other open PRs touching the same files?
+- Is this PR a subset of a larger mega-PR? (common with vibe coding — person keeps working, creates multiple PRs from evolving branch)
+- Would merging this and another PR cause conflicts?
+
+#### 4. Destructive operations
+- Graph: Any `DELETE`, `DETACH DELETE` that could remove data?
+- Files: Any file deletions that could break other commands? Check if deleted files are referenced elsewhere.
+- Endpoints: Any API endpoint removals that could break the website or other consumers?
+- Schema: Any node/relationship type removals?
+
+#### 5. Security regression
+- Does it remove boundary rules, permission checks, or security guards?
+- Does it remove `.syncignore` entries (controls what gets synced to public repo)?
+- Does it weaken auth flows or token validation?
+- Does it expose secrets (hardcoded tokens, API keys, credentials)?
+- Does it add world-readable temp files with sensitive content?
+
+#### 6. Schema consistency
+- New node types or relationships must be declared in CLAUDE.md schema line
+- Property naming must follow existing conventions (camelCase, not snake_case)
+- Relationships must use UPPER_SNAKE_CASE
+
+#### 7. Idempotency
+- Graph writes must use `MERGE` not `CREATE` for edges/nodes that could be created twice
+- Scripts that run on schedule or can be retried must produce the same result on re-run
+- Exception: `CREATE` is OK for truly unique entities (e.g. new Session per session)
+
+#### 8. Error handling in critical path
+- Does `set -euo pipefail` at script top risk killing the script before essential output?
+- Are graph queries guarded with `|| true` or fallback values?
+- Do hooks always `exit 0` (observe/report hooks must never block)?
+
+#### 9. Convention violations
+- `.env` must never be sourced (`source .env` breaks on spaces) — use `grep '^KEY=' .env | cut -d'=' -f2-`
+- Hardcoded absolute paths from developer's machine (e.g. `/Users/cemdagdelen/...`)
+- Committed lock files, `.DS_Store`, or session-specific state
+- Dead code (unreachable cases, unused imports)
+
+#### 10. Stale base
+- How far behind `develop` is the branch?
+- Are there guaranteed merge conflicts with current develop?
+- Has the same file been modified on develop since the PR was created?
+
+### Agent output format
+
+Each agent must return a structured assessment:
+
+```
+PR: #NNN — Title
+Author: name
+Branch: branch-name
+Size: +X/-Y, N files
+Created: date
+
+CHECKLIST:
+1. Works:          PASS/FAIL/WARN — details
+2. Side effects:   PASS/FAIL/WARN — details
+3. Overlap:        PASS/FAIL/WARN — details
+4. Destructive:    PASS/FAIL/WARN — details
+5. Security:       PASS/FAIL/WARN — details
+6. Schema:         PASS/FAIL/WARN — details
+7. Idempotency:    PASS/FAIL/WARN — details
+8. Error handling: PASS/FAIL/WARN — details
+9. Conventions:    PASS/FAIL/WARN — details
+10. Stale base:    PASS/FAIL/WARN — details
+
+BLOCKING ISSUES:
+- [list or "None"]
+
+RISK: LOW / MEDIUM / HIGH
+VERDICT: MERGE / FIX THEN MERGE / NEEDS WORK / REJECT
+```
+
+## Step 3: Compile results
+
+Wait for all agents to complete. Sort PRs into tiers:
+
+### Tier classification
+
+| Tier | Criteria | Action |
+|------|----------|--------|
+| **Tier 1: Easy merge** | 0 FAILs, 0-2 WARNs, LOW risk | Merge immediately |
+| **Tier 2: Fix then merge** | 1-2 FAILs (minor), MEDIUM risk | Fix specific issues, then merge |
+| **Tier 3: Needs work** | 3+ FAILs or HIGH risk | Send back with fix list |
+| **Tier 4: Reject** | Security regression, broken imports, or fundamentally wrong approach | Close with explanation |
+
+### Overlap resolution
+
+If multiple PRs touch the same files:
+1. Identify which is the "superset" (mega-PR)
+2. Recommend merge order to minimize conflicts
+3. Flag PRs that should be closed as superseded
+
+## Step 4: Render summary
+
+### Single PR review
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  ✧ REVIEW                                         oz · Mar 11      │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  PR #241 — Fix session date sort                                     │
+│  Author: cem · Branch: dev/cem/identity-fragmentation-fix            │
+│  Size: +11/-11 · 4 files · Created: Mar 6                           │
+│                                                                      │
+│  CHECKLIST                                                           │
+│    ✓ Works              Correct Cypher pattern                       │
+│    ✓ Side effects       API files only                               │
+│    ✓ Overlap            None                                         │
+│    ✓ Destructive        No deletes                                   │
+│    ✓ Security           No regression                                │
+│    ✓ Schema             No changes                                   │
+│    ✓ Idempotency        N/A (read queries)                           │
+│    ✓ Error handling     Existing guards preserved                    │
+│    ✓ Conventions        Clean                                        │
+│    ⚠ Stale base         5 days old, low conflict risk                │
+│                                                                      │
+│  BLOCKING: None                                                      │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  Risk: LOW · Verdict: MERGE                                         │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Multi-PR review (sorted by tier)
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  ✧ REVIEW                                         oz · Mar 11      │
+│  14 open PRs from cem · 10 unique (4 superseded)                    │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  TIER 1 — EASY MERGE                                                │
+│    #241  Fix session date sort              +11/-11    LOW    MERGE  │
+│    #267  Handoff claiming                   +58/-2     LOW    MERGE  │
+│    #185  Rewrite /meeting                   +586/-734  LOW    MERGE  │
+│                                                                      │
+│  TIER 2 — FIX THEN MERGE                                            │
+│    #266  PR graph nodes                     +167/-7    MED    FIX    │
+│          → Cypher bug: LIMIT before SKIP                             │
+│    #265  /summon command                    +207/-0    LOW    FIX    │
+│          → Missing schema declaration                                │
+│                                                                      │
+│  TIER 3 — NEEDS WORK                                                │
+│    #244  Deep-reflect redesign              +604/-711  MED-HI WORK  │
+│          → Non-idempotent edges, bash YAML parsing                   │
+│    #269  Granola API upgrade                +1096/-228 MED    WORK  │
+│          → Bundled unrelated changes, User-Agent spoof               │
+│                                                                      │
+│  TIER 4 — REJECT / CLOSE                                            │
+│    #202  Extract CLAUDE.md into skills      +299/-247  HIGH   REJCT │
+│          → Security rules deleted, not extracted                     │
+│    #268  Coder workspace cleanup            +179/-488  HIGH   REJCT │
+│          → .syncignore deleted, missing import, role overwrite       │
+│                                                                      │
+│  SUPERSEDED (close)                                                  │
+│    #264  → by #256                                                   │
+│    #265  → by #256                                                   │
+│    #272  → by #256                                                   │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  Merge order: #241 → #267 → #185 → #266 → #265                     │
+│  3 ready · 2 fixable · 2 need work · 2 reject · 3 superseded        │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Step 5: Offer next actions
+
+After showing the summary, offer:
+- **"Start merging Tier 1?"** — if there are easy merges
+- **"Show details for #NNN?"** — deep dive on a specific PR
+- **"Fix #NNN?"** — checkout the branch, apply fixes, push
+
+## Merge execution (when user confirms)
+
+For each PR to merge:
+```bash
+GITHUB_TOKEN=$TOKEN gh pr merge $PR_NUM --merge --repo $GITHUB_ORG/$REPO_NAME
+```
+
+After merge, update local develop:
+```bash
+git fetch origin develop --quiet
+```
+
+For PRs to close (superseded):
+```bash
+GITHUB_TOKEN=$TOKEN gh pr close $PR_NUM --comment "Superseded by #NNN" --repo $GITHUB_ORG/$REPO_NAME
+```
+
+## Edge cases
+
+| Scenario | Handling |
+|----------|----------|
+| PR already merged | Skip, note in output |
+| PR has merge conflicts | Flag in stale-base check, cannot auto-merge |
+| PR targets main (not develop) | Warning — all PRs should target develop |
+| Author is maintainer (oz) | Still run full checklist, but note trusted author |
+| Mega-PR detected | Identify sub-PRs, recommend close superseded |
+| No open PRs | "No open PRs found." |
+| Graph offline | Skip Cypher validation checks, note limitation |

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

@@ -0,0 +1,92 @@
+---
+name: save
+description: "Save current Egregore work: validate distribution, commit the task branch, push it, and create or reuse a PR against the configured integration branch."
+---
+
+Save work without asking the user to manage Git mechanics.
+
+## When to invoke
+
+Use for “save”, “commit and push”, “push this work”, or `$save`. When the user
+is ending a session and needs a durable continuation record, use `handoff` or
+`wrap` first; their canonical writes are already independently durable.
+
+## Contract
+
+- `bin/agent.sh save` is the one runtime-neutral Git transaction for Claude,
+  Codex, Pi, and Prime.
+- Resolve the integration branch from `egregore.json`; never hardcode
+  `develop` or `main`.
+- Do not scan or mutate the graph before/after saving. Canonical lifecycle and
+  projection repair are separate Runtime operations.
+- Do not repeat canonical artifact writeback. Save only outstanding repository
+  changes and already-created memory records.
+- The current Git/GitHub transport remains valid but is behind the sync
+  boundary; GitHub identity is not ActorIdentity.
+
+## Flow
+
+1. Inspect branch, working-tree changes, memory changes, ahead count, and an
+   existing PR. A clean tree can still need a push/PR when the branch is ahead.
+2. Resolve the configured base once:
+
+```bash
+BASE=$(bash -c 'SCRIPT_DIR="$PWD"; CONFIG="$PWD/egregore.json"; . "$PWD/bin/lib/config.sh" && _get_base_branch')
+```
+
+Stop before mutation if it cannot be resolved.
+
+3. Run the product-distribution checkpoint when its registry exists — the
+   guard is real: installed instances do not ship the distribution engine,
+   and its absence there is correct, not an error to chase:
+
+```bash
+if [ -f bin/capability-distribution.mjs ] && [ -f capability-distribution.json ]; then
+  bash bin/node-run.sh bin/capability-distribution.mjs validate --root .
+  bash bin/node-run.sh bin/capability-distribution.mjs changes --root . --base "origin/$BASE" --json
+  bash bin/node-run.sh bin/capability-distribution.mjs runtime-skill-audit --root . --strict-contract
+fi
+```
+
+Ask one placement question only for a genuinely new/unclassified component or
+an explicit placement change. Ordinary edits to an existing component do not
+prompt.
+
+4. Derive:
+
+- a short topic;
+- a commit subject/body under `.claude/context/commit-format.md`;
+- a PR body under `.claude/context/pr-format.md`, including honest
+  verification for non-Markdown changes.
+
+If unrelated changes make the save scope ambiguous, show one Save all / Narrow
+scope checkpoint. Otherwise continue without ritual confirmation.
+
+5. Execute exactly once:
+
+```bash
+bin/agent.sh save \
+  --message "$MESSAGE" \
+  --topic "$TOPIC" \
+  --pr-body "$PR_BODY"
+```
+
+The bridge owns branch safety, exact commits, push, PR create/reuse, and memory
+sync. Do not run manual Git commands around it or trigger a graph scan.
+
+6. Report only the branch, commit/push outcome, PR URL/reuse, memory sync, and
+any failed step. Local commits remain safe if transport fails.
+
+## Rules
+
+- Never push directly to a protected integration/stable branch.
+- Never use destructive Git commands.
+- Never auto-close handoffs or todos during save.
+- Never publish or notify as an implied side effect.
+- Do not spend a Loom/model-routing turn on deterministic save mechanics.
+
+Emit content-free command telemetry after the bridge returns:
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"save"}' 2>/dev/null &
+```

package/runtime/claude/.claude/skills/slack-connect/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: slack-connect
+description: "Set up Slack as a notification channel for your Egregore — creates the workspace app, invites the bot, and binds a channel. Use for /slack-connect, 'connect slack', or 'set up slack notifications'."
+---
+
+Set up Slack as a notification channel for your Egregore.
+
+Arguments: $ARGUMENTS (none expected)
+
+## When to invoke
+
+**Trigger phrases:**
+- "set up slack", "connect slack", "slack-connect"
+- "add slack notifications", "slack channel", "notify us on slack"
+
+**Disambiguation:**
+- "set up telegram" → `/telegram-connect`
+- "set up teams" → `/teams-connect`
+- "send a message to slack" → NOT this — use the separate notification
+  consent protocol in `.claude/context/notification-consent.md`
+
+## What this does
+
+Connects one Slack channel to Egregore notifications using an app the org
+creates in its own workspace. After this, everything that plans a group
+notification may also resolve Slack as a receiving channel; all resolved
+channels are shown before separate dispatch approval.
+
+The privacy contract, stated plainly to the user: **the install screen will
+say only "Send messages as @Egregore." The app cannot read messages — the
+manifest requests one scope, `chat:write`.** The workspace owns the app and
+the token; revoking either cuts Egregore off instantly.
+
+**Works in both modes.** Check which one first:
+```bash
+MODE=$(jq -r '.mode // "connected"' egregore.json 2>/dev/null)
+```
+- **local** — the token stays in the gitignored `.env` on this machine and
+  messages go straight from here to Slack. No Egregore server is in the path.
+- **connected** — the token is stored on the org's row so the hosted service
+  can deliver group notifications from any member's session.
+
+Only Step 5 differs between the modes.
+
+## Step 0: Prerequisites
+
+1. A Slack workspace where this person can install apps. Some workspaces
+   require admin approval for new apps — if theirs does, the install in
+   Step 2 turns into a request the admin must approve first.
+2. Nothing to install locally. No CLI, no cloud account.
+
+## Step 1: Create the app from the manifest (human, ~1 min)
+
+Show the manifest:
+```bash
+cat slack-app/manifest.yml
+```
+(If this instance doesn't carry `slack-app/`, fetch it from the framework repo.)
+
+Guide them: **https://api.slack.com/apps** → **Create New App** →
+**From a manifest** → pick their workspace → paste the manifest → **Create**.
+
+## Step 2: Install and copy the bot token (human, 2 clicks + 1 paste)
+
+**Settings → Install App → Install to Workspace** → **Allow**.
+
+Then copy the **Bot User OAuth Token** from the same page. It starts with
+`xoxb-`. Validate the prefix when they paste it:
+- `xoxb-` — correct.
+- `xoxp-` (user token) or `xapp-` (app-level token) — wrong item on the
+  page; point them back to **Install App → Bot User OAuth Token**.
+
+Do not store it anywhere yet.
+
+## Step 3: Invite the bot to the channel (human, 1 line)
+
+In the target channel: `/invite @Egregore` (or channel name → **Integrations**
+→ **Add apps**). With only `chat:write`, the bot can post solely in channels
+it is a member of — skipping this yields `not_in_channel` at send time.
+
+## Step 4: Channel ID (human pastes, agent validates)
+
+Ask for the channel ID: channel name → **About** tab → **Channel ID** at the
+bottom (or the `/archives/C…` segment of a channel link).
+
+Validate: must match `^[CG][A-Z0-9]{6,}$`. A `D…` id is a DM — not supported;
+ask for a channel.
+
+Smoke-test the token before persisting anything (no message is sent):
+```bash
+curl -sS https://slack.com/api/auth.test -H "Authorization: Bearer <TOKEN>"
+```
+`"ok":true` proves the token and names the workspace — confirm it is the one
+they expect. `invalid_auth` here means a mispasted or revoked token; fix now,
+not at send time.
+
+## Step 5: Persist
+
+**Local mode** — token to `.env` (gitignored — never commit), channel to
+`.egregore-state.json` (NOT `egregore.json` — the state file is untracked and
+shared across worktrees):
+```bash
+printf 'SLACK_BOT_TOKEN=%s\n' '<TOKEN>' >> .env
+jq '.slack_channel_id = "<CHANNEL_ID>" | .slack_channel_name = "<#channel-name>"' \
+  .egregore-state.json > .egregore-state.json.tmp && mv .egregore-state.json.tmp .egregore-state.json
+```
+
+**Connected mode** — store on the org so any member's session can deliver:
+```bash
+API_URL=$(jq -r '.api_url' egregore.json)
+KEY=$(grep '^EGREGORE_API_KEY=' .env | cut -d= -f2-)
+curl -sS -X POST "$API_URL/api/org/slack" \
+  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
+  -d '{"channel_id":"<CHANNEL_ID>","bot_token":"<TOKEN>","channel_name":"<#channel-name>"}'
+```
+Expect `{"status":"connected", …}`.
+
+## Step 6: Verify with separate exact notification consent
+
+Follow `.claude/context/notification-consent.md`. Connecting Slack is not
+consent to send a test message. Prepare after configuration is final:
+```bash
+PLAN_JSON=$(bash bin/notify.sh plan group "Slack channel connected — this message reached you through Egregore.")
+```
+
+Show every resolved receiving channel—potentially Telegram, Teams, and
+Slack—and the exact message in a dedicated Send / Edit / Cancel checkpoint.
+Only dispatch after Send is selected for that preview.
+
+## Troubleshooting quick table
+
+| Symptom | Cause → fix |
+|---|---|
+| `invalid_auth` | Wrong, revoked, or other-workspace token → Step 2, re-copy from Install App |
+| `not_in_channel` | Bot not invited to the channel → Step 3 |
+| `channel_not_found` | Wrong channel ID, or a private channel the bot isn't in → Step 4 / invite it |
+| `missing_scope` | App not created from the manifest → recreate from Step 1, reinstall |
+| `account_inactive` | App was uninstalled from the workspace → reinstall |
+| `ratelimited` | Transient — retried automatically |
+| Install becomes an approval request | Workspace requires admin approval → the admin approves, then continue |
+| Local plan omits slack from channels | Half-configured: `SLACK_BOT_TOKEN` missing from `.env` or `slack_channel_id` missing from `.egregore-state.json` |
+
+## After
+
+Emit telemetry (fire-and-forget):
+```bash
+bash bin/telemetry.sh emit "slack-connect" '{"command":"slack-connect"}' 2>/dev/null &
+```