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

package/runtime/claude/.claude/skills/ingest-user-interview/references/analysis-contract.md

@@ -0,0 +1,125 @@
+# User-interview analysis contract
+
+## Analysis topology
+
+Start with a compact scaffold of evidence-bearing moments:
+
+- friction;
+- aha;
+- feature gap;
+- mental-model mismatch;
+- feature discovery;
+- suggestion;
+- unresolved reference.
+
+For short interviews, analyze inline. For long or complex interviews, three
+parallel lenses may help:
+
+1. Journey: tasks, stages, critical path, friction, aha moments, stuck points,
+   completion, abandonment, and drop-off risk.
+2. Sentiment: emotional arc, engagement, confusion, delight, frustration,
+   hesitation, confidence, energy, and what went unsaid. Read this lens fresh,
+   without letting the scaffold predetermine it.
+3. Product: feature discovery, mental models, unmet needs, workarounds,
+   comparisons, suggestions, feasibility, priority, and relevant quests.
+
+Synthesize rather than concatenate. Treat disagreements between lenses as
+signal: completion plus frustration, abandonment plus curiosity, discovery
+plus a missed step, delight plus mental-model mismatch, or blocker severity
+plus only mild emotion.
+
+## Briefing
+
+Write `# Interview Analysis: {participant} — {type} Interview` with date,
+participant, researcher, source, emotional arc, and engagement. Include:
+
+- opinionated meta-analysis: heart, journey reality versus intended design,
+  emotional read, and specific product implications;
+- journey map, critical path, and drop-off risks;
+- friction and aha moments;
+- feature discovery and mental-model mismatches;
+- unmet needs and suggestions;
+- internal analytical tensions;
+- extracted insights with confidence/priority/quest links;
+- open questions and a concise participant journey note.
+
+Do not generalize one participant into all users. Prefer “this participant
+experienced X.” Every durable insight needs source evidence; excerpts are at
+most 120 characters.
+
+## Insight mapping
+
+- friction, aha, feature gap, feature discovery, suggestion -> `finding`
+- mental model or cross-participant recurrence -> `pattern`
+- an explicit accepted product choice -> `decision`
+
+Preserve category, confidence, severity, emotional context, journey stage,
+priority, speaker, topics, quest relationships, and whether cross-participant
+evidence exists in `metadata` and the Markdown body. Researcher commitments
+remain actions, not knowledge artifacts.
+
+## Proposal
+
+Show the emotional arc, engagement, 2-3 sentence reading, proposed insights
+with evidence and confidence, tensions, and actions. Ask `Save`, `Edit`, or
+`Skip`. Only `Save` authorizes canonical writeback; publication and
+notification require later, separate approvals.
+
+## Runtime package
+
+Create one temporary JSON package:
+
+```json
+{
+  "schema_version": "egregore-research-ingest/v1",
+  "kind": "interview",
+  "source": {
+    "type": "granola|file|paste",
+    "id": "stable source identity",
+    "revision": "source revision or content hash",
+    "content_hash": "required SHA-256 of the acquired source"
+  },
+  "documents": [
+    {
+      "artifact_type": "interview",
+      "title": "Interview: Sarah — onboarding",
+      "canonical_path": "research/interviews/2026-08-27-sarah.md",
+      "body_path": "/temporary/egregore-interview-briefing.md",
+      "metadata": {
+        "participant": "Sarah",
+        "researcher": "oz",
+        "interview_type": "onboarding",
+        "engagement": "high"
+      }
+    },
+    {
+      "artifact_type": "participant",
+      "title": "Sarah",
+      "canonical_path": "research/participants/sarah.md",
+      "body_path": "/temporary/egregore-interview-participant.md"
+    },
+    {
+      "artifact_type": "finding",
+      "title": "Setup concealed the API-key step",
+      "canonical_path": "knowledge/findings/2026-08-27-api-key-step.md",
+      "body_path": "/temporary/egregore-interview-finding.md",
+      "metadata": {
+        "category": "friction",
+        "confidence": 0.9,
+        "priority": "p0_blocker",
+        "severity": "blocker",
+        "speaker": "participant"
+      },
+      "relationships": [
+        {"relation": "from_interview", "target_id": "artifact id of briefing"}
+      ]
+    }
+  ]
+}
+```
+
+Body paths point to temporary analysis output, never directly to canonical
+memory. The package may contain at most 40 Markdown documents. Runtime
+authorizes all artifact identities before reading bodies, validates allowed research paths,
+writes the package in one Git provenance commit, refreshes the derived index
+once, starts one changed-hash embedding job, and emits content-free telemetry.

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

@@ -0,0 +1,111 @@
+---
+name: invite
+description: "Invite someone to this Egregore — repository access plus a setup link when Connected. Use for /invite <username>, 'invite <username>', or 'add <username> to the org'; not member removal."
+---
+
+# Egregore invite
+
+Invite one future organization member through the Egregore Runtime. The
+GitHub username is a linked-provider alias used by today's access transport;
+it is not an Egregore account, actor, or membership identifier.
+
+## When to invoke
+
+Invite someone to this Egregore — repository access plus a setup link when Connected. Use for /invite <username>, 'invite <username>', or 'add <username> to the org'; not member removal.
+
+## Input
+
+Require one GitHub username. If it is missing, show and stop:
+
+```text
+Usage: /invite <github-username>
+
+Example: /invite newuser
+```
+
+## Execute
+
+Run exactly one invitation transaction and capture its JSON receipt:
+
+```bash
+INVITE_JSON=$(bash bin/invite.sh "$ARGUMENTS")
+```
+
+The adapter resolves `ActorContext`, keeps `AccountIdentity`, `ActorIdentity`,
+and `OrgMembership` separate, authorizes `ADMINISTER` before external effects,
+and selects the current GitHub or Connected control-plane transport. It owns
+credentials, repository grants, the provisional canonical invitation record,
+path-scoped Git provenance, and sanitized error mapping. Do not call GitHub,
+the Egregore API, graph, storage providers, or Git directly.
+
+Connected service permission denials are authoritative. Explain that an
+organization admin must invite the person and show `manual_access_url` when
+the receipt contains one. Never infer permission from a GitHub username.
+
+## Render
+
+For an accepted Connected invite with `invite_url`:
+
+```text
+Inviting {provider_username} to {org_name}...
+
+  Repository access: {provider_status}
+  Memory access:     {memory_status}
+  Invite link:       created
+
+Share this link with {provider_username}:
+
+  {invite_url}
+
+They'll authenticate, accept the access invitation, and receive
+the install command.
+```
+
+For an accepted Local invite:
+
+```text
+Invited {provider_username} to {org_name}.
+
+  Repository access: {provider_status}
+  Memory record:     {memory_status}
+
+Tell them to run:
+
+  {join_command}
+```
+
+Append the returned group link when present. Render warnings truthfully and
+use the returned manual access URL for failed repository grants. Never show
+raw JSON, tokens, request bodies, or internal identity IDs.
+
+## Optional direct notification — separate consent
+
+The invite action never authorizes a message. Only when a direct destination
+exists and the user wants Egregore to deliver the link, create a fresh
+actor-bound notification plan for this exact message:
+
+```text
+You've been invited to {org_name} on Egregore! Join here: {invite_url-or-command}
+```
+
+Write it to a mode-0600 temporary file, then run:
+
+```bash
+PLAN_JSON=$(bash bin/notification.sh plan --kind send \
+  --recipient "$ARGUMENTS" --message-file "$MESSAGE_FILE")
+```
+
+Show the exact organization, recipient, every channel, and message in a
+dedicated **Send / Edit / Cancel** checkpoint. Dispatch only after fresh exact
+approval using the notification Runtime's approve/dispatch commands. Never
+fall back from direct delivery to a group, reuse old approval, retry from a
+detached task, or treat sharing the invite link as notification consent.
+
+## Rules
+
+- Local works without graph or Connected infrastructure.
+- Connected preserves the existing seven-day setup-link behavior.
+- An invite is provisional authority to create a future membership. Do not
+  mint an AccountIdentity, ActorIdentity, or OrgMembership for the invitee.
+- Existing onboarded profiles are never overwritten by an invitation stub.
+- Notification consent and membership-invite authorization are separate.

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

@@ -0,0 +1,104 @@
+---
+name: issue
+description: "Report and manage organizational issues through Egregore Runtime. Use for 'this is broken', 'bug in', 'file an issue', 'report a problem', issue listing/search, or closing an issue; do not use for a personal todo or collaborative quest."
+---
+
+# Issue
+
+Use the Runtime adapter for internal issue state. Canonical Markdown and Git
+are authoritative in Local and Connected modes; graph, GitHub, and notification
+systems are optional consumers.
+
+## When to invoke
+
+Report and manage organizational issues through Egregore Runtime. Use for 'this is broken', 'bug in', 'file an issue', 'report a problem', issue listing/search, or closing an issue; do not use for a personal todo or collaborative quest.
+
+## Route
+
+- Empty or `list` → `bash bin/issue.sh list`
+- `list open|closed|all` → `bash bin/issue.sh list --status <status>`
+- `show <id-or-title>` → `bash bin/issue.sh show "<reference>"`
+- `search <term>` → `bash bin/issue.sh search "<term>"`
+- `close <id-or-title>` → `bash bin/issue.sh close "<reference>"`
+- Anything else → create mode
+
+Render returned JSON as the established 72-column issue card. Never expose raw
+JSON. Preserve stable `artifact_id` and `canonical_path` in detail views.
+
+## Retrieval and speed
+
+Reuse `EGREGORE_ORG_CONTEXT_V1` when it already contains sufficient issue
+evidence. Do not issue a second organizational query. The adapter resolves
+list/show/search/close from one authorized canonical snapshot. If explicit
+additional recall is necessary, use the search skill once, then open the
+selected canonical source through the Runtime boundary.
+
+## Create
+
+Derive a concise title and keep the user's wording as the description. Ask only
+for information required to avoid a materially wrong record. Then call once:
+
+```bash
+bash bin/issue.sh create \
+  --title "$TITLE" \
+  --description "$DESCRIPTION" \
+  --recipient "$RECIPIENT" \
+  --topic "$TOPIC"
+```
+
+Add `--context` or `--suggested-fix` only when supplied or already known. The
+adapter resolves ActorContext, authorizes WRITE, creates typed provenance, and
+runs one CanonicalArtifactWriteback transaction:
+
+`authorize → validate → Markdown → Git provenance → derived-index refresh → telemetry`
+
+Do not write issue Markdown, run Git, update retrieval indexes, or project graph state here.
+Do not auto-save again after an accepted or partial writeback receipt.
+
+## Close
+
+Resolve the canonical issue first. If multiple references match, show a compact
+picker and wait. Close only after a direct user request; age never closes an
+issue. `bin/issue.sh close` updates the same stable artifact through one
+authorized writeback. It does not close a linked GitHub issue automatically.
+
+## GitHub publication
+
+Creating or closing a GitHub issue is a separate SHARE action, never implied by
+internal creation/closure. Prepare the exact immutable preview:
+
+```bash
+bash bin/issue.sh share-preview "$ISSUE" --action create --repo owner/name
+# linked issue only:
+bash bin/issue.sh share-preview "$ISSUE" --action close
+```
+
+Show destination, exact title, and exact body/action. Ask Send / Edit / Cancel
+and stop. Only after Send for that exact preview:
+
+```bash
+bash bin/issue.sh share-github --confirm "$CONFIRMATION_TOKEN"
+```
+
+The token is short-lived and bound to the unchanged canonical issue and exact
+destination. Never call `gh issue` directly. A successful create records the
+returned GitHub URL through a separate canonical provenance writeback.
+
+## Notifications
+
+Issue creation/publication is not notification consent. If the user separately
+asks to notify someone, follow `.claude/context/notification-consent.md`: plan
+through `bin/notify.sh`, show organization, exact recipient/channels/message,
+then obtain one exact Send / Edit / Cancel decision. Never notify automatically
+and never treat GitHub approval as notification approval.
+
+## Invariants
+
+- Authorize discover/read before issue content is loaded; authorize write/share
+  separately before those actions.
+- ActorIdentity, organization identity, artifact identity, and Git provenance
+  remain stable across providers and harnesses.
+- Graph state never overrides or blocks canonical issue behavior.
+- GitHub and notifications are never part of the canonical write transaction.
+- Do not include transcripts or sensitive content in external previews unless
+  the user explicitly selected and reviewed that exact content.

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

@@ -0,0 +1,81 @@
+---
+name: me
+description: "View or change the current member's Egregore profile across Claude Code, Codex, Pi, and Prime. Use for /me, 'who am I', 'call me <name>', or an explicit self email update."
+---
+
+# Egregore identity
+
+Use the Runtime identity adapter. Account identity, actor identity,
+organization membership, and provider aliases are separate concepts:
+
+- `AccountIdentity` is the provider-independent authenticated account.
+- `ActorIdentity` is the person, agent, or service acting in this session.
+- `OrgMembership` supplies organization, role, and team context.
+- GitHub is an optional linked provider and current transport alias. Its login
+  or numeric ID is never the Egregore account or actor identity.
+
+External people discovered during ingestion remain source-scoped identities;
+this workflow never promotes them into organizational members.
+
+## When to invoke
+
+View or change the current member's Egregore profile across Claude Code, Codex, Pi, and Prime. Use for /me, 'who am I', 'call me <name>', or an explicit self email update.
+
+## Show
+
+Run once:
+
+```bash
+bash bin/person.sh show
+```
+
+The adapter resolves `ActorContext` and authorizes `read` on the current
+identity before returning anything. Display the preferred name, linked
+provider alias, explicitly supplied email, and aliases. Do not expose internal
+IDs unless the user requests diagnostics.
+
+## Change preferred name
+
+For an explicit self-update:
+
+```bash
+bash bin/person.sh set-name "$ARGUMENTS"
+```
+
+The identity adapter validates the value, preserves previous names as aliases,
+authorizes `administer` on the current identity, and reconciles the same stable
+account/actor/membership records. Report the returned status without exposing
+raw JSON.
+
+## Change email
+
+Only when the authenticated user explicitly supplies their own address:
+
+```bash
+bash bin/person.sh set-email "person@example.com"
+```
+
+Never infer an email from Git configuration or unrelated source content.
+
+## Reconcile
+
+Use this only for onboarding, a linked-provider rename, or an identity repair:
+
+```bash
+bash bin/person.sh sync
+```
+
+The adapter owns Local/Connected reconciliation and optional derived
+projections. Do not call storage providers or edit identity files directly.
+A partial result means canonical Local identity is retained and the named
+external reconciliation can be retried.
+
+## Rules
+
+- Preferred name is organization-scoped; stable account and actor IDs survive
+  provider changes.
+- Authentication never grants membership, retrieval scope, or action
+  permission by itself.
+- Do not hand-edit `.egregore-state.json`, people profiles, membership state,
+  or projections.
+- Emit only content-free command telemetry.

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

@@ -0,0 +1,76 @@
+---
+name: meeting
+description: "Analyze a Granola meeting into an evidence-backed briefing, decisions, findings, patterns, actions, and continuity. Use for /meeting, /meeting sync, /meeting backfill, or requests to process a meeting."
+---
+
+# Meeting
+
+Acquire meeting material, adapt the analysis to the user's intent, preview the
+result, then persist one approved typed package through Egregore Runtime.
+
+Read [references/analysis-contract.md](references/analysis-contract.md) before
+analysis or package construction.
+
+## When to invoke
+
+Analyze a Granola meeting into an evidence-backed briefing, decisions, findings, patterns, actions, and continuity. Use for /meeting, /meeting sync, /meeting backfill, or requests to process a meeting.
+
+## Source
+
+Use the configured Granola connector to list/search meetings and fetch the
+selected transcript plus title, date, attendees, source ID, and source
+revision. Do not copy connector credentials or raw transcripts into canonical
+memory.
+
+- `/meeting`: list recent candidates and let the user choose.
+- `/meeting <search>`: select an exact result or ask when ambiguous.
+- `/meeting sync`: process selected new candidates with balanced defaults.
+- `/meeting backfill`: re-analyze selected canonical meeting sources; never
+  overwrite newer claims without explicit supersession.
+
+If Granola is unavailable, explain the connection issue and stop. Connector
+access is source acquisition, not organizational authorization or canonical
+writeback.
+
+## Context and intent
+
+Reuse sufficient `EGREGORE_ORG_CONTEXT_V1`. Open already-selected canonical
+evidence through the Runtime source-open boundary when exact verification is
+needed. Do not repeat Observe/search merely because this skill loaded.
+
+If compiled context is insufficient and continuity materially matters, make at
+most one Egregore retrieval call, then open only relevant canonical sources.
+Never query graph/QMD directly. Canonical Markdown/Git wins on disagreement.
+
+For one interactive meeting, ask briefly what matters and whether the user
+wants quick extraction or deeper dynamics/continuity. Skip questions when the
+request already specifies intent, and in sync/backfill mode.
+
+## Analyze and approve
+
+Choose only useful lenses from the reference. Inline analysis is the fast
+default; parallel analysts are optional for long or complex transcripts.
+Actions remain separate from durable decisions/findings/patterns.
+
+Show a concise preview with the heart of the meeting, evidence, confidence,
+relationships, tensions, and actions. Ask `Save`, `Edit`, or `Skip`. Do not
+write before `Save`.
+
+## Canonical writeback
+
+Build one temporary `egregore-research-ingest/v1` package from the approved
+briefing and extracted artifacts, then make exactly one deterministic call:
+
+```bash
+bash bin/research-ingest.sh meeting --input "$PACKAGE_JSON"
+```
+
+Runtime owns authorization, schema/path validation, stable identity,
+provenance, canonical Markdown, Git provenance, derived-index refresh,
+background embedding, and telemetry. Do not separately write files, mutate a
+processed-meetings cache, run `/save`, or manage graph projection.
+
+Report accepted/partial/rejected status and canonical paths from the receipt.
+Graph projection, publication, and notifications are optional later effects.
+Each requires its own capability/permission boundary; publication and every
+notification also require a separate exact user approval.

package/runtime/claude/.claude/skills/meeting/references/analysis-contract.md

@@ -0,0 +1,102 @@
+# Meeting analysis contract
+
+Use only the lenses that serve the user's stated intent and the material.
+
+## Lenses
+
+- Substance: decisions, findings, patterns, actions, dependencies, evidence,
+  tradeoffs, confidence, and open questions.
+- Dynamics: tone arc, conviction, alignment, divergence, and energy shifts.
+- Continuity: what changed, repeated, resolved, superseded, or disappeared.
+- Criticality: unnamed risks and gaps between stated confidence, behavior, and
+  organizational reality.
+
+Do not manufacture depth for a short operational meeting. Inline analysis is
+the fast default. Use parallel analysts only for long or genuinely complex
+material and only when the harness supports them.
+
+## Briefing
+
+Write `# Meeting Intelligence: {title}` followed by source/date/attendees,
+analysis approach, and user intent. Include only useful sections:
+
+1. Meta-analysis: heart of the conversation; genuinely new information;
+   actuality against current canonical context; concrete considerations.
+2. Tone and energy, dynamics, or convictions when those lenses were applied.
+3. Priorities and dependencies.
+4. Decision evolution and cross-meeting patterns when canonical evidence
+   supports them.
+5. Analytical tensions where lenses or evidence disagree.
+6. Actions as a separate list, not durable knowledge artifacts.
+7. Extracted artifacts and unresolved threads.
+
+Write as a trusted colleague briefing someone who missed the meeting. Lead
+with the gravitational center, prioritize ruthlessly, and name who should do
+what. An execution meeting with no new ground may say exactly that.
+
+## Extracted knowledge
+
+Persist only `decision`, `finding`, or `pattern` documents. For each preserve:
+
+- title and substantive content;
+- context, rationale, and tradeoffs where present;
+- confidence calibrated to evidence;
+- speaker and an evidence excerpt no longer than 120 characters;
+- topics, open questions, urgency, importance, and conviction;
+- explicit evolution/supersession and related-artifact links.
+
+Strong agreement or data-backed evidence is about 0.9; a single speaker about
+0.7; exploration about 0.5; contentious evidence about 0.6. Do not preserve
+small talk, logistics, trivia, or claims absent from the source.
+
+## Proposal
+
+Before writeback, show a compact preview containing the analysis approach,
+intent, heart of the conversation, each proposed artifact with confidence and
+evidence, tensions, actions, and relationships. Ask `Save`, `Edit`, or `Skip`.
+Only `Save` authorizes canonical writeback; it does not authorize publication
+or notification.
+
+## Runtime package
+
+Create one temporary JSON package:
+
+```json
+{
+  "schema_version": "egregore-research-ingest/v1",
+  "kind": "meeting",
+  "source": {
+    "type": "granola",
+    "id": "granola-document-id",
+    "revision": "source revision or content hash",
+    "content_hash": "required SHA-256 of the acquired source",
+    "uri": "optional source URI"
+  },
+  "documents": [
+    {
+      "artifact_type": "meeting",
+      "title": "Weekly Sync",
+      "canonical_path": "meetings/2026-08-27-weekly-sync.md",
+      "body_path": "/temporary/egregore-meeting-briefing.md",
+      "status": "active",
+      "metadata": {"attendees": ["alice", "bob"], "intent": "full analysis"}
+    },
+    {
+      "artifact_type": "decision",
+      "title": "Use typed hybrid retrieval",
+      "canonical_path": "knowledge/decisions/2026-08-27-typed-hybrid.md",
+      "body_path": "/temporary/egregore-meeting-decision.md",
+      "relationships": [
+        {"relation": "from_meeting", "target_id": "artifact id of briefing"}
+      ],
+      "supersedes": []
+    }
+  ]
+}
+```
+
+Body paths point to temporary analysis output, never directly to canonical
+memory. The package may contain at most 40 Markdown documents. Runtime
+authorizes all artifact identities before reading document bodies, validates paths/schema,
+writes the package in one Git provenance commit, updates the derived index once,
+starts one changed-hash embedding job, and emits content-free telemetry.

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

@@ -0,0 +1,71 @@
+---
+name: note
+description: "Use when the user says 'jot this down', 'note to self', 'just thinking out loud', or 'park this thought' — saves an actor-owned private draft locally and promotes it to organizational knowledge only on an explicit request."
+---
+
+# Note
+
+Capture a half-baked thought for the active actor. Private notes are local draft
+state, not canonical organizational truth, and are never committed, indexed,
+published, shared, or notified automatically.
+
+## When to invoke
+
+Use when the user says 'jot this down', 'note to self', 'just thinking out loud', or 'park this thought' — saves an actor-owned private draft locally and promotes it to organizational knowledge only on an explicit request.
+
+## Commands
+
+- No arguments: ask what to capture.
+- Content: infer a short title and one of `thought`, `session`,
+  `retrospective`, or `journal`; write the user's meaning without polishing it
+  into a decision.
+- `list`: call `bash bin/knowledge.sh note-list` and format the returned notes.
+- `share <title>` or `promote <title>`: select the actor's note, preview it,
+  choose `decision`, `finding`, or `pattern`, and explicitly confirm promotion.
+
+## Capture
+
+Render only the note body to a temporary file, then call:
+
+```bash
+bash bin/knowledge.sh note-create \
+  --title "{title}" \
+  --type "{thought|session|retrospective|journal}" \
+  --input "$TMP_NOTE"
+```
+
+The Runtime adapter resolves ActorContext and authorizes the actor before local
+private persistence. The resulting envelope carries stable actor identity and
+a private policy hint. The hint describes posture; authorization remains the
+Runtime policy decision.
+
+## Promotion
+
+Open the selected note through `bash bin/knowledge.sh note-open "{path}"`.
+After the user explicitly approves organizational promotion, call:
+
+```bash
+bash bin/knowledge.sh note-promote \
+  --path "{path}" \
+  --type "{decision|finding|pattern}" \
+  --title "{title}" \
+  --topic "{topic}" \
+  --workstream "{workstream}"
+```
+
+Promotion uses CanonicalArtifactWriteback: authorize, assign stable typed
+identity and source provenance, persist Markdown, record Git provenance, update
+retrieval, start background embedding, then emit content-free telemetry. The
+private copy remains and records the canonical target.
+
+## Boundaries
+
+- Do not access another actor's note or treat policy hints as authorization.
+- Do not call Git, QMD, graph, telemetry, publishing, sharing, notification, or
+  control-plane mechanics directly.
+- `share` means promotion into authorized organizational Markdown, not external
+  publication. External sharing and notification require separate permission
+  and exact consent.
+
+Confirm private capture with its local path. Confirm promotion with the new
+canonical path and writeback status.