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

package/runtime/claude/.claude/skills/deep-reflect/RESEARCH.md

@@ -0,0 +1,132 @@
+# RESEARCH.md — the engine contract
+
+How multi-hop research actually works: the ledger, leads, waves, saturation, and budgets. `SKILL.md` is the entry point; this file is the mechanism. Agent prompts live in `ROLES.md`.
+
+## The ledger
+
+Main-loop state, mirrored to `.egregore/research-runs/{run-id}.json` after every wave (and on any exit — the ledger survives skipped runs and crashes; it is the provenance):
+
+```json
+{
+  "run_id": "dr-2026-07-11-a3f2",
+  "question": "...",
+  "sub_questions": ["..."],
+  "mode": "question|crossref",
+  "band": "brief|standard|deep",
+  "seen": ["memory/knowledge/decisions/2026-03-07-....md"],
+  "lead_queue": [{"type": "quest", "ref": "onboarding-validation", "why": "...", "from": "path", "wave": 1, "score": 6}],
+  "claims": [{"id": 1, "claim": "...", "sub_question": "...", "path": "...", "excerpt": "...", "date": "...", "author": "...", "weight": "primary|secondary|ambient", "wave": 1, "status": "pending|verified|corrected|downgraded|dated|killed|unverified", "relation": "crossref mode only"}],
+  "gaps": [{"id": 1, "gap": "...", "probes": ["..."], "from": "scout|reader|analyst|coverage", "status": "provisional|verified|refuted"}],
+  "log": [{"action": "...", "purpose": "...", "result": "..."}],
+  "stop_reason": null
+}
+```
+
+**The main loop assigns a stable integer `id` to every claim and gap when merging agent output into the ledger.** All downstream references (analysts' `claim_ids`, skeptics' verdicts) use these ids — never positional indices, since analysts and skeptics receive differently ordered or partitioned views.
+
+`seen` holds normalized repo-relative paths (plus graph ids when connected). A doc enters `seen` when assigned to a reader, never twice.
+
+## Leads
+
+A **lead** is a typed pointer extracted by a reader from document text or graph neighbors:
+
+```
+{type: doc-link | quest | person | session | pr | topic-term | named-absent, ref, why, from, wave}
+```
+
+Extraction sources map to real substrate affordances — readers look for:
+- explicit `memory/` paths and relative `.md` links in prose
+- frontmatter fields, BOTH generations (`ROLES.md` §Frontmatter): YAML `topics:[]` / `quests:[]` / `harvest:` / `synthesis:` / `affects:`, and old-style `**Topics**:` bold-field lines
+- author names in filenames (`DD-author-topic.md`) and bylines
+- branch names, PR numbers, and hosted URLs in handoff prose
+- `handoffs/index.md` and `quests/index.md` ledger rows
+- connected mode: graph neighbors via the `filePath` bridge — `PART_OF`, `IMPLEMENTS` chains, `BUILDS_ON`/`SUPERSEDES`/`REFINES`, `RELATES_TO`/`TENSION_WITH` (prior deep-reflect output is a hop rail)
+
+**Lead resolution** (main loop, between waves) converts non-doc leads to files:
+- `person` → `ls memory/handoffs/*/ | grep {author}` + `memory/people/{name}.md` (+ graph `CONTRIBUTED_BY` when connected)
+- `quest` → `memory/quests/{slug}.md` + frontmatter grep for members
+- `session` → handoff filePath via `handoffs/index.md`
+- `topic-term` → exactly ONE `search.sh query "{term}" --fast -n 5`. Topic leads may NOT recursively spawn topic leads — fan-out control.
+- `named-absent` → never hops. The main loop runs ONE `--fast` resolution probe; on miss, it enters the gap register with that probe attached.
+
+## Graph orientation (connected mode, seed stage only)
+
+One query, non-fatal, results fed to the scouts:
+
+```bash
+bash bin/graph.sh query "MATCH (a:Artifact) WHERE any(t IN a.topics WHERE t CONTAINS \$topic) OR toLower(a.title) CONTAINS \$topic OPTIONAL MATCH (a)-[r:RELATES_TO|TENSION_WITH|PART_OF]-(n) RETURN a.title, a.type, a.filePath, type(r), coalesce(n.title, n.id) LIMIT 25" '{"topic": "{lowercased core topic term}"}' 2>/dev/null || true
+```
+
+## Gaps
+
+The gap register has three feeders, all routed by the main loop:
+
+1. **Scout `gap_hypotheses`** — paired with that scout's `probes_run` list when entered into the register.
+2. **Coverage probes** — after each wave, any sub-question with zero claims gets ≤2 main-loop `--fast` probes; if both miss, a gap entry is written with those probe strings.
+3. **Reader `named-absent` leads and analyst `void` patterns** — folded into the register before VERIFY; the main loop attaches originating probes where they exist.
+
+The skeptic receives the FULL gap register. For probe-less gaps it devises ≥2 probes itself. Only gaps that survive the skeptic's absence audit (`ROLES.md` §Skeptic) ship in the report.
+
+## Waves
+
+A **hop = one wave**: pop the top-K leads (K sized so resolved docs ≤ 8-12), resolve to files, batch into 2-4 parallel readers (3-6 files each — readers read their files in their OWN contexts; never pipe file contents through the main loop), merge results into the ledger.
+
+**Lead scoring** for the queue: novelty (unseen: hard filter) × source-strength (citing doc's relevance verdict: high=3 / med=2 / low=1) × type-prior (doc-link, quest = 3 · person, session, pr = 2 · topic-term = 1), recency as tiebreak.
+
+## Saturation
+
+Three tests, checked after every wave:
+
+- **(a) novelty low**: unseen leads / total leads extracted this wave < 0.25
+- **(b) coverage met**: every sub-question has ≥2 independent sources (distinct authors OR distinct top-level dirs), OR a gap entry with ≥2 distinct failed probes (**provisional** — VERIFY re-attacks it later)
+- **(c) yield zero**: no primary-weight claims this wave
+
+Stop rules, as explicit predicates:
+
+| stop_reason | Fires when |
+|---|---|
+| `answered` | Self-termination: before the budget, every sub-question has ≥2 sources including ≥1 primary claim, and the main loop judges further waves enrichment, not necessity. Don't spend to budget if strong synthesis is found early |
+| `saturated` | (b) holds AND ((a) OR (c)) |
+| `dry` | (a) AND (c) hold for two consecutive waves while (b) still fails — the corpus stopped yielding before coverage completed |
+| `budget` | Wave cap reached (brief 1 / standard 3 / deep 5) |
+| `sparse` | FRAME collapsed the run to the sparse band |
+
+**Bonus wave rule**: if VERIFY refutes a gap claim (the skeptic found the doc), the found doc enters the ledger; if that leaves a sub-question uncovered, reopen ONE budget-exempt bonus wave — at most once per run. Bonus-wave claims go through a scoped second skeptic pass (mechanical + semantic checks only; no further gap re-search or decay audit). Analysts are NOT re-run; bonus-wave claims ship as findings only if verified, and patterns stand as pruned (`REPORT.md` §Pattern pruning).
+
+## Budget
+
+Set in FRAME. **Counting rule for N (relevant docs):** union of unique paths from (1) `grep -ril "{topic terms}" memory/knowledge/ memory/handoffs/ memory/artifacts/`, (2) 2× `search.sh query --fast -n 20` with different wordings (count result blocks, not the banner), (3) `bin/artifacts.sh find "{topic}"`. N = the union's size; it feeds the plan line and this table:
+
+| N | Band | Waves |
+|---|---|---|
+| ≥ ~35, multi-dir spread | deep-leaning standard | 3 (5 on `--deep`) |
+| ~20-35 | standard | 3 |
+| ~5-20 | collapsed | 1 scout + 1 wave, insufficiency-forward report |
+| < ~5 | none | offer `/reflect` or `/harvest`, stop |
+
+If `search.sh` errors, warns `index update FAILED`, or returns zero blocks while grep/`artifacts.sh` hit: drop it from the union, rely on grep + artifacts.sh, and note "recall degraded" in the plan line — a broken index must not masquerade as a thin corpus.
+
+`--brief`/`--deep` force the band. Search budget holds regardless: ONE best-available-tier probe per run (seed, scout #1), `--fast` elsewhere.
+
+## Compounding
+
+SEED must check prior research before searching cold:
+
+1. `grep -ril "{topic terms}" memory/knowledge/research/ | head -5`
+2. For each prior report found: read `artifacts_cited` (falling back to `artifacts_consulted` — the older generation) from its frontmatter. Entries may be filename STEMS rather than paths — resolve with `find memory -name "{stem}.md"` before promoting. Resolved paths become pre-warmed hop-0 leads (source-strength high).
+3. Re-audit the prior report's `null_regions` frontmatter (structured gaps + probes): *"was this gap filled since?"* is a standing sub-question.
+4. The new report stamps `builds_on: [prior-report-paths]` in frontmatter (+ `BUILDS_ON` edge, connected).
+
+Only user-saved reports exist in `memory/knowledge/research/`, so compounding never seeds from ungated output.
+
+## Decay
+
+During VERIFY: any cited evidence older than ~90 days triggers ONE `--fast` newer-artifact probe (`search.sh query "{claim terms}" --fast -n 3`, or `SUPERSEDES` edge check when connected). A newer contradicting or superseding artifact demotes the claim to `dated` and is cited alongside it. In cross-ref mode this check may also set the claim's `relation` to `supersedes`.
+
+## Resume
+
+`--resume <run-id>`: load `.egregore/research-runs/{run-id}.json` and restore the FULL ledger — `seen`, `lead_queue`, `claims`, `gaps`, `log`. Continue under the original `run_id` and file. "Fresh budget" means the wave counter resets under the original band unless `--brief`/`--deep` is re-passed. The prior `stop_reason` is appended to `log` as `{action: "resumed"}`.
+
+## Cross-ref mode differences
+
+Identical engine. The insight text is decomposed into sub-questions of the form: *what supports this? what contradicts it? what already says it? what does it depend on?* Readers additionally set `relation` on each claim (`supports | contradicts | duplicates | depends-on` — derived from which sub-question the claim answers; `supersedes` is set only by the skeptic's decay check). The skeptic preserves or corrects `relation` alongside its verdict. Verified relations drive the capture stage's edge proposals (`REPORT.md` §Writeback).

package/runtime/claude/.claude/skills/deep-reflect/ROLES.md

@@ -0,0 +1,104 @@
+# ROLES.md — agent contracts
+
+Prompts and output schemas for every subagent the engine spawns. Contracts are **tier-silent** — no model names anywhere; spawns pass no model override and inherit the session tier. Each prompt must be self-contained: subagents inherit nothing from the main conversation.
+
+**Two bindings, one contract.** When the harness provides schema-validated subagent spawning (the Workflow tool), bind each role's schema there and validation is enforced by the harness. In the foreground-Task fallback, append to every prompt: `Return ONLY valid JSON matching the schema below. No markdown fences, no explanation.` — one repair attempt on invalid JSON, then continue with whatever agents succeeded; synthesis works with partial input.
+
+Every prompt begins with the same context block:
+
+> You are a research subagent inside Egregore, an org whose shared memory lives as markdown under `memory/` (absolute path: {MEMORY_PATH}). The org is researching: "{QUESTION}" (sub-questions: {SUB_QUESTIONS}). Your final output is consumed by an orchestrator as data.
+
+## Frontmatter — two generations, both real
+
+Files carry EITHER new-style YAML (`title:`, `date:` or `created:`, `author:` or `researcher:`/`by:`, `topics: [..]`, `quests: [..]`, `status:`) OR old-style bold-field headers (`**Date**:`, `**Author**:`, `**Topics**:`). Parse both, honoring the synonyms. When neither exists, derive date/author from the filename (`YYYY-MM-DD-author-slug.md`, `DD-author-topic.md` in monthly dirs). Never report a file as unattributed or undated without checking all three.
+
+## Scout (SEED — 2 in parallel)
+
+Mission: build the initial frontier. You may hypothesize what you expect to find, but you may NOT assert any finding as real — that requires evidence you don't have yet.
+
+Inputs: question, sub-questions, corpus-probe results, prior-research compounding leads (`RESEARCH.md` §Compounding), and (connected) the graph orientation results.
+
+Actions budget: ≤3 `bash bin/search.sh query "..." --fast -n 5` with DIFFERENT wordings (one keyword-ish, one conceptual); frontmatter/topic greps (`grep -rl "topics:.*{term}" memory/knowledge/`); `memory/quests/index.md` + `memory/handoffs/index.md` scans. **Scout #1's prompt additionally grants the run's single best-available-tier search probe (no `--fast` flag); scout #2 is `--fast`-only** — the main loop writes this into each prompt so the budget needs no coordination. Count result blocks, never the banner hit count.
+
+```json
+{
+  "candidates": [{"path": "memory/...", "hypothesis": "why this doc should matter"}],
+  "probes_run": ["..."],
+  "gap_hypotheses": ["topics that SHOULD have coverage but probes found none"]
+}
+```
+
+Max 12 candidates across both scouts after the main loop merges. Prefer breadth — convergence needs sources from different directories and authors. The main loop pairs your `gap_hypotheses` with your `probes_run` when it enters them into the gap register.
+
+## Reader (HOP WAVES — 2-4 per wave)
+
+Mission: read assigned files IN FULL, in your own context, and extract claims + leads. Titles and topics are hints, not evidence — your claims must be grounded in what the text actually says.
+
+Inputs: 3-6 file paths (you read them yourself with the Read tool), the question + sub-questions, the current seen-set (paths only, for lead dedup), and in cross-ref mode the relation instruction below.
+
+Hard rules:
+- No claim without a verbatim excerpt (≤30 words) copied exactly from the file — it will be mechanically re-checked; a fabricated or paraphrased excerpt kills the claim.
+- Weight every claim: `primary` (should change what the user does next), `secondary` (worth knowing), `ambient` (context).
+- Irrelevant assigned file → say so (`relevance: low`) and move on. Don't force significance.
+- Extract leads per `RESEARCH.md` §Leads; skip anything in the seen-set.
+- Cross-ref mode only: set `relation` per claim — `supports | contradicts | duplicates | depends-on`, derived from which sub-question the claim answers. Never `supersedes` (that verdict belongs to the skeptic's decay check).
+
+```json
+{
+  "claims": [{"claim": "one sentence", "sub_question": "...", "path": "memory/...", "excerpt": "verbatim ≤30 words", "date": "YYYY-MM-DD", "author": "...", "weight": "primary|secondary|ambient", "relation": "cross-ref mode only"}],
+  "leads": [{"type": "doc-link|quest|person|session|pr|topic-term|named-absent", "ref": "...", "why": "one line", "from": "citing path"}],
+  "contradiction_flags": [{"between": ["path-or-claim", "path-or-claim"], "note": "..."}],
+  "file_verdicts": [{"path": "...", "relevance": "high|med|low"}]
+}
+```
+
+The main loop assigns each claim a stable `id` on merge; you never number your own claims.
+
+## Analyst (PATTERN — 2 in parallel, de-correlated)
+
+Mission: find structure across the ledger's claims. You receive the id-carrying claims table and contradiction flags — NOT the other analyst's output, intentionally: fresh reads without anchoring.
+
+**Convergence analyst** — receives claims sorted chronologically. Look for: independent agreement (distinct authors/dirs arriving at the same conclusion), evolution arcs (thinking that shifted, and when), clusters, trajectories.
+**Tension analyst** — receives claims grouped by sub-question/topic. Look for: contradictions, supersession (a newer claim quietly replacing an older one), drift (vocabulary or position changing without a recorded decision), voids (what the claims collectively assume but never establish).
+
+Hard rules:
+- Every pattern names its supporting claims by their stable `id`s. No pattern without ≥1 claim (voids cite what SHOULD exist but doesn't; the main loop routes voids into the gap register for the skeptic's absence audit).
+- Describe patterns in free language, tagged with a structural role. **The role vocabulary is open**: `cluster / bridge / void / trajectory / recurrence / contradiction / drift / convergence` are the common labels — coin a new one when the structure genuinely demands it, and define it in the description.
+- "The claims are routine; nothing structural" is a valid finding. Don't manufacture significance.
+
+```json
+{
+  "patterns": [{"role": "free-form structural label (common: cluster|bridge|void|trajectory|recurrence|contradiction|drift|convergence)", "description": "free-form, specific", "claim_ids": [1, 4], "weight": "primary|secondary|ambient"}],
+  "notes": "free-form observations that don't fit the schema"
+}
+```
+
+## Skeptic (VERIFY — 1-2 in parallel)
+
+Mission: attack every claim and every gap. You see id-carrying claims + cited files + the full gap register — never the analysts' reasoning. When two skeptics run, the main loop partitions claims by id; both receive the whole gap register but only audit their assigned gap ids.
+
+Per claim, in order:
+1. **Mechanical check.** Normalize both sides — strip markdown emphasis characters (`*`, `_`, `` ` ``), collapse every whitespace run (including newlines) to a single space, case-fold — then fixed-string search the normalized excerpt in the normalized file text (read the file, or `python3`/`tr`-normalize and grep). Found → step 2. Missing → search the file yourself for text genuinely supporting the claim: found → replace the excerpt with the real text, verdict `corrected`; not found → verdict `killed` (miscite — no paraphrase benefit of the doubt).
+2. **Semantic check.** Does the surrounding text carry the claim's weight, or only its title? Overreach → verdict `downgraded` (with a note), not killed.
+3. **Decay check.** Evidence older than ~90 days → ONE `search.sh query "{claim terms}" --fast -n 3` (or `SUPERSEDES` edge check when connected). Newer superseding/contradicting artifact → verdict `dated`, cite the newer doc; in cross-ref mode set the claim's `relation` to `supersedes`.
+4. Cross-ref mode: preserve the claim's `relation` unless your findings correct it; note any change.
+
+Per gap:
+5. **Absence audit.** Re-run the recorded probes PLUS one adversarial probe of your own devising (different vocabulary, different directory). Probe-less gaps (analyst voids): devise ≥2 probes yourself. If you FIND the allegedly-absent doc: verdict `refuted`, return the found path — it enters the ledger as a bonus hop. Otherwise `verified`.
+
+```json
+{
+  "claim_verdicts": [{"claim_id": 1, "verdict": "verified|corrected|downgraded|dated|killed", "note": "...", "corrected_excerpt": "only for corrected", "newer_doc": "only for dated", "relation": "cross-ref mode, only if changed"}],
+  "gap_verdicts": [{"gap_id": 1, "verdict": "verified|refuted", "found_path": "only for refuted", "extra_probes": ["the probes you added"]}]
+}
+```
+
+## Failure handling
+
+| Failure | Handling |
+|---|---|
+| One reader/scout returns invalid JSON | One repair attempt; still invalid → log to provenance, continue partial |
+| One analyst fails | Proceed with the other; note the missing lens in the report |
+| Both analysts fail | Main loop synthesizes directly from the verified claims table at capped confidence |
+| Skeptic fails | Rerun once; else every unchecked claim ships marked `unverified` — never silently skip verification |
+| An agent returns zero claims/leads | Valid result. Record it; it feeds the yield saturation test |

package/runtime/claude/.claude/skills/deep-reflect/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: deep-reflect
+description: "Run deep, multi-hop research over org memory to answer a question or cross-reference an insight, with a cited synthesis. Use for /deep-reflect — not one-shot recall (/search) or capturing an insight (/reflect)."
+---
+
+Deep research over org memory — ask a question, get a verified, cited synthesis of what the org collectively knows, including what it doesn't.
+
+Multi-hop, multi-agent research over `memory/` (plus the graph, when connected). Waves of parallel readers hop a lead ledger until saturation; a skeptic pass kills every claim it cannot re-find in the cited file. `/reflect` captures user thought; `/deep-reflect` researches what the org already knows.
+
+Pipeline: deep-reflect v4 · 2026-07-11 · thin entry + sibling contracts (`RESEARCH.md`, `ROLES.md`, `REPORT.md`).
+
+## When to invoke
+
+User says: "deep dive on X", "what do we know about X", "what does the knowledge base say about X", "research what we know about X", "what's the org's position on X", "cross-reference this", "analyze this against what we know", "connect the dots between X and Y"
+Not this: web sources → out of scope (this skill researches memory, not the web) · one-shot recall ("what did we decide about X") → `/search` · capture a new insight → `/reflect` · ask people, not documents → `/harvest` · private thought → `/note` · track the open question itself → `/quest`
+
+Arguments: $ARGUMENTS (Optional: [question or insight] [--brief|--deep] [--quest <slug>] [--no-capture] [--resume <run-id>] [--graph])
+
+**Saves through the capture gate.** A Save verdict runs the full `/save` flow — no separate `/save` after.
+
+## Modes
+
+| Mode | Job | Extra output |
+|---|---|---|
+| **question** (default) | Answer a research question from memory | — |
+| **cross-ref** | v2's job: situate one insight against the corpus | verified `RELATES_TO`/`TENSION_WITH` edge proposals (connected) |
+
+Both modes write reports to `memory/knowledge/research/` — except `--brief` and probe-collapsed sparse runs, which default to terminal-only output with a two-option Save/Skip gate (Save writes the standard file). Depth bands are orthogonal; the default is dynamic, set by the Stage-0 corpus probe:
+
+| Band | Waves | Docs read | Wall clock |
+|---|---|---|---|
+| `--brief` | 1 | ~8 | ~1-2 min |
+| standard | ≤3 | ~24 | ~3-5 min |
+| `--deep` | ≤5 | ~45 | ~6-10 min |
+
+**Detection order (Stage 0):** 1) strip flags; 2) interrogative form ("what/how/why/have we/do we…") → question mode; 3) "cross-reference" / "this" / a pronoun pointing at conversation content, or a declarative insight statement → cross-ref mode (the research question becomes *"how does {insight} sit against existing memory?"*); 4) bare topic noun-phrase → question mode with *"what does the org know about {topic}?"*; 5) empty and no session context → one AskUserQuestion offering 2-3 candidate questions mined from the current session, or stop cleanly on skip.
+
+## Mode detection
+
+```bash
+MODE=$(jq -r '.mode // "connected"' egregore.json 2>/dev/null)
+```
+
+**IMPORTANT**: Check mode FIRST, before any other step.
+
+**Local mode** (`mode === "local"`): run the FULL engine over files. `bin/search.sh` is fully local; frontmatter topics/quests, `index.md` ledgers, and filename conventions are the hop rails. Skip ALL `bin/graph.sh` / `bin/graph-op.sh` calls — do NOT run them. Zero graph vocabulary in any output (no "graph offline", no Neo4j, no connected-mode upsell). Cross-references persist as markdown links in the report. TUI footer: `✓ Saved · pushed`.
+
+**Connected mode**: uses the same canonical file path. Graph orientation and
+edge extraction occur only when the user explicitly supplies `--graph`; graph
+health/freshness must be verified and every selected claim must still open its
+canonical source. A Connected account alone never adds graph to retrieval.
+
+**Connected but graph offline**: DOES message, once — `Graph offline — researching over files only.` — then runs the local-shaped plan. Every graph call throughout is non-fatal (`2>/dev/null || true`); the file is the canonical record.
+
+## Execution rules
+
+- **Dialogue budget (hard rule):** at most ONE AskUserQuestion before the run — fired only when the question is underspecified (combine scope confirmation + depth choice in that single call). A long estimate alone never requires confirmation — the plan line is the notice. Plus the capture gate at the end, including any user-initiated follow-up branches inside it. Never more.
+- **Plan line before any work:** `Researching: {question} · ~{N} relevant docs · budget {M} waves · est ~{X} min` — N per `RESEARCH.md` §Budget's counting rule. Pre-announce any single long operation (`semantic search ~30s…`).
+- **Wave ticker while running:** `[wave 2/3] read 11 · claims 9 · new leads 6 (2 quests, 1 person, 3 files)`.
+- **Observe seed:** import candidates and already-opened sources from an
+  attached `EGREGORE_ORG_CONTEXT_V1` block into the evidence ledger. Do not
+  query or reopen them again. When the seed sufficiently covers the question,
+  Stage 0 performs zero additional retrieval calls.
+- **Search budget:** without a sufficient Observe seed, run at most ONE typed
+  `bin/search.sh query` call for initial discovery. Later searches are allowed
+  only for a named uncovered sub-question or lead, never as a duplicate corpus
+  probe or dedupe pass.
+- **CRITICAL: Suppress raw output.** Never show raw JSON or file dumps. Bulk payloads go to `"${TMPDIR:-/tmp}/egregore-research-$$.json"` and get jq-sliced.
+- Call inventory: 1 identity resolution · 0-1 initial Runtime retrieval ·
+  authorized opens for uncovered evidence · bounded lead probes only when a
+  named gap survives · subagents per the selected band · 0-1 pre-run question
+  · 1 capture gate · one canonical writeback · telemetry.
+- Run ID: `dr-$(date +%Y-%m-%d)-$(openssl rand -hex 2)`. Ledger persists at `.egregore/research-runs/{run-id}.json` (local only, never pushed) — including for skipped runs. The log IS the provenance, not a byproduct.
+
+## Orchestration
+
+Invoking this skill IS the user's opt-in to Workflow orchestration for this run. Compose workflow scripts at runtime from `RESEARCH.md` (stages, ledger, saturation) and `ROLES.md` (agent contracts + schemas). Do NOT ship or reuse a stored `.js` — the prose contracts are the single source of truth.
+
+**The seam:** one Workflow invocation per stage fan-out — the scouts, each wave's readers, the analysts, the skeptics. The main conversation performs lead resolution, ledger merge/mirror, and saturation checks BETWEEN invocations. Readers read their assigned files in their own contexts — never pipe file contents through the main loop.
+
+**Workflow tool unavailable** (older harness, org policy): run the SAME stages as standard foreground parallel Task calls (NOT `run_in_background`) binding the same `ROLES.md` contracts — JSON by prompt discipline, one repair attempt, then continue with whatever agents succeeded. This fallback is a first-class path with the identical seam structure. Runtimes with no subagents at all (some Codex sessions) degrade further per the Codex adapter: staged single-model passes, provenance marked `verification: self-checked`.
+
+Spawns pass NO model override — subagents inherit the session tier (`loom/routes.json` carries the delegation note; Loom Phase 1 does not let skills pin models). Framing, synthesis, and the capture gate stay in the main loop.
+
+## Stages
+
+Engine contract: `RESEARCH.md`. Agent prompts + schemas: `ROLES.md`. Report, TUI, capture: `REPORT.md`.
+
+0. **FRAME** (main loop) — parse per detection order; import the attached
+   Observe evidence ledger first; issue one Runtime query only when that seed
+   is absent or leaves a named coverage gap; estimate N from the resulting
+   candidates; decompose into 2-4 sub-questions and print the plan line.
+1. **SEED** (2 scouts, parallel) — build the initial frontier (≤12 docs): search probes, frontmatter/index greps, prior-research compounding (`RESEARCH.md` §Compounding), one graph orientation query (connected only). Scout #1 holds the run's single best-available-tier search probe; scout #2 is `--fast`-only.
+2. **HOP WAVES** (2-4 readers per wave, loop) — readers read their assigned files in their own contexts and return claims-with-verbatim-excerpts + typed leads. Main loop merges into the ledger (assigning stable claim/gap ids), dedupes, scores, resolves top leads to files, probes uncovered sub-questions (`RESEARCH.md` §Gaps), checks saturation, schedules next wave or stops.
+3. **PATTERN** (2 analysts, de-correlated) — convergence lens and tension lens over the id-carrying claims table; the tension analyst never sees convergence output. Disagreement between analysts is preserved as a finding, never averaged.
+4. **VERIFY** (1-2 skeptics) — mechanical excerpt check (kill on fabrication), semantic support check (downgrade on overreach), adversarial gap re-search (a found doc refutes the gap and enters the ledger), decay probe on evidence older than ~90 days. A refuted gap may reopen ONE bonus wave; bonus-wave claims get a scoped second skeptic pass (`RESEARCH.md` §Saturation). The kill count is reported.
+5. **SYNTHESIZE** (main loop) — prune patterns whose support died (`REPORT.md` §Pattern pruning); stance, not summary: 2-4 paragraphs that tell the user something they don't already know. Confidence is derived from evidence structure, never self-reported. Insufficiency map assembled from surviving gap claims. Register: analyst, not critic — "the memory shows X", never "the team is failing to Y".
+6. **PRESENT** (main loop) — answer → findings (◆/◇ with inline path citations) → tensions & disagreements → what memory doesn't hold → provenance footer. The evidence appendix goes in the report file, NOT chat. No TUI box yet.
+7. **CAPTURE?** (main loop) — one AskUserQuestion: **Save** (default) / **Edit first** / **File follow-ups** (gaps → `/quest` or `/harvest` stubs) / **Skip**. Writeback per `REPORT.md`, then render the ◈ TUI box reflecting the ACTUAL outcome. Skip leaves only the local ledger — no memory writes, no graph writes.
+
+## Telemetry
+
+Fire-and-forget after the run completes or exits early (single emit — not at frame):
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"deep-reflect","mode":"question","waves":3,"docs_read":24,"stop_reason":"saturated","duration_ms":210000}' 2>/dev/null &
+```
+
+All extended fields optional; never include the question text or file paths.
+
+## Edge cases
+
+| Scenario | Handling |
+|---|---|
+| Topic-sparse probe (<~20 relevant docs) | Collapse to 1 scout + 1 wave + inline synthesis; announce "memory is thin here"; ship an insufficiency-forward report — sparse IS a finding |
+| Ultra-sparse (<~5 relevant docs) | Say so; offer `/reflect` (capture what you know) or `/harvest` (ask people) instead of faking research |
+| `search.sh` errors, warns `index update FAILED`, or returns zero blocks while grep/`artifacts.sh` find hits | Fall back to the grep-based corpus probe before classifying the corpus as sparse; note "recall degraded" in the plan line |
+| Workflow tool unavailable | Foreground parallel Task fan-out per §Orchestration |
+| Hybrid search models not on disk | `--fast` everywhere; zero inline downloads |
+| Graph down (connected) | One-line note, local-shaped plan, non-fatal calls |
+| Reader/analyst fails mid-wave | Log to provenance, continue partial; both analysts fail → main loop synthesizes from the verified claims table at capped confidence |
+| Skeptic fails | Rerun once; else every unchecked claim ships marked `unverified` in the report and say so — never skip verification silently |
+| No findings survive | "Memory holds nothing structural on this" is a valid report. Don't manufacture significance |
+| Memory symlink missing | Error: "Run /setup first" |
+| File collision on save | Append 4-char hex to slug |
+| User skips capture | Ledger remains at `.egregore/research-runs/` — nothing else is written |
+
+## Example
+
+```
+> /deep-reflect what do we actually know about onboarding drop-off?
+
+Researching: onboarding drop-off · ~34 relevant docs · budget 3 waves · est ~4 min
+[wave 1/3] read 10 · claims 8 · new leads 9 (3 files, 2 quests, 1 person)
+[wave 2/3] read 9 · claims 6 · new leads 4 (2 files, 1 session)
+[wave 3/3] skipped — saturated (novelty 0.18, all sub-questions covered)
+Verifying 14 claims + 3 gaps… 1 claim cut (miscite) · 1 gap refuted (doc found → read)
+
+[ANSWER — 3 paragraphs of stance]
+[FINDINGS — ◆ primary / ◇ secondary with path citations]
+[TENSIONS — including one analyst disagreement, preserved]
+[WHAT MEMORY DOESN'T HOLD — 2 verified gaps + the probes that prove them]
+3 waves · 20 docs read · 11 cited · 1 claim cut in verification · stopped: saturated
+
+[AskUserQuestion: Save (default) / Edit first / File follow-ups / Skip]
+> Save
+
+[1/3] ✓ Writing knowledge/research/2026-07-11-cem-onboarding-drop-off.md
+[2/3] ✓ Indexed in knowledge graph (4 edges)
+[3/3] ✓ Auto-saved
+
+┌──────────────────────────────────────────────────────────────────────┐
+│  ◈ DEEP REFLECT                                       cem · Jul 11   │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Q: what do we know about onboarding drop-off?                       │
+│  ◆ 3 primary · ◇ 4 secondary findings · confidence: high             │
+│  3 waves · 20 docs read · 11 cited · 1 claim cut in verification     │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  ✓ Saved · graphed · pushed                                          │
+│  Visible in /activity.                                               │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Backwards compatibility
+
+- Report artifacts use `type: research` and land in `memory/knowledge/research/` (established by the Mar 7 redesign; `findings/` remains `/reflect`'s lane).
+- Prior v2 `RELATES_TO`/`TENSION_WITH` edges are read as hop rails and extended (cross-ref mode, verified claims only). Old edges keep working.
+- The v2 invocation phrases all still route here; `quick|focused|deep` keyword syntax is retired in favor of `--brief`/`--deep` + dynamic default.

package/runtime/claude/.claude/skills/delete-user/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: delete-user
+description: "Remove a member from this Egregore, revoking access across GitHub, Supabase, and Neo4j. Use for /delete-user, removing or kicking someone — not inviting (/invite) or viewing members (/dashboard)."
+---
+
+Remove a member from this Egregore. Revokes access across GitHub, Supabase, and Neo4j.
+
+## When to invoke
+
+User says: "remove user", "delete user", "kick", "revoke access", "remove member", "remove them", "delete member"
+Not this: invite someone → `/invite` · view members → `/dashboard`
+
+Arguments: $ARGUMENTS (Required: GitHub username of the person to remove)
+
+## Execution rules
+
+**CRITICAL: Suppress raw output.** Never show raw JSON to the user. All API calls MUST capture output in a variable and only show formatted status lines.
+
+**CRITICAL: Never expose credentials in tool output.**
+- Never read tokens in a separate bash call — always inline.
+- All credential handling happens inside a single bash call that only outputs the formatted result.
+
+## Step 1: Validate
+
+If `$ARGUMENTS` is empty, show usage and stop:
+```
+Usage: /delete-user <github-username>
+
+Example: /delete-user someuser
+
+Modes (you'll be asked):
+  revoke — Remove access, keep their contributions
+  full   — Remove access and erase their data
+```
+
+## Step 2: Confirm
+
+Ask the user to confirm via AskUserQuestion:
+
+```
+question: "How should {username} be removed from this org?"
+header: "Remove mode"
+options:
+  - label: "Revoke access"
+    description: "Remove GitHub + Supabase access. Keep their sessions, artifacts, and contributions in the knowledge graph."
+  - label: "Full delete"
+    description: "Revoke access AND erase their sessions, profile, todos, and telemetry. Artifacts and quests are kept but orphaned."
+  - label: "Cancel"
+    description: "Don't remove anyone."
+```
+
+If "Cancel", stop with: `Cancelled.`
+
+Map "Revoke access" → `mode=revoke`, "Full delete" → `mode=full`.
+
+## Step 3: Remove (single call — credentials stay hidden)
+
+Run ONE bash call with description "Removing {username} from org":
+
+```bash
+bash -c '
+USERNAME="$1"
+MODE="$2"
+TOKEN=$(grep "^GITHUB_TOKEN=" .env | cut -d"=" -f2-)
+API_URL=$(jq -r ".api_url" egregore.json)
+SLUG=$(jq -r ".slug // .org_name" egregore.json)
+
+if [ -z "$TOKEN" ]; then
+  echo "ERROR: No GitHub token found. Run: bash bin/github-auth.sh"
+  exit 1
+fi
+
+RESP=$(curl -s -X DELETE "$API_URL/api/org/$SLUG/members/$USERNAME?mode=$MODE" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN")
+
+echo "$RESP" | jq -c "{
+  ok: (if .status == \"removed\" then true else false end),
+  status: .status,
+  mode: .mode,
+  username: .username,
+  actions: .actions,
+  errors: .errors,
+  error: .detail
+}"
+' -- "$ARGUMENTS" "MODE"
+```
+
+Replace `MODE` with the actual mode value (`revoke` or `full`).
+
+## Step 4: Display result
+
+Parse the JSON output from Step 3. **Never show raw JSON to the user.**
+
+**Success** (ok=true, mode=revoke):
+```
+Removing {username} from {org_name}...
+
+  GitHub access:   revoked
+  Membership:      deactivated
+  Knowledge graph: marked as removed
+
+{username} can no longer access this Egregore.
+Their contributions are preserved in the graph.
+```
+
+**Success** (ok=true, mode=full):
+```
+Removing {username} from {org_name}...
+
+  GitHub access:   revoked
+  Membership:      deactivated
+  Sessions:        deleted
+  Contributions:   orphaned (artifacts kept)
+  Person node:     deleted
+  Telemetry:       deleted
+
+{username} has been fully removed from this Egregore.
+```
+
+If `errors` array is non-empty, append:
+```
+Partial failures (non-fatal):
+  - {error1}
+  - {error2}
+```
+
+**Auth error** (ok=false):
+```
+Cannot remove {username}: {error}
+```
+
+Common errors:
+- "Only org admins or platform admins can remove members" → you need admin role
+- "Cannot remove an admin. Change their role first." → target is an admin
+- "No active membership found" → user isn't a member or already removed
+
+## Step 5: Telemetry (fire-and-forget)
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"delete-user"}' 2>/dev/null &
+```
+
+## Rules
+
+- **Only org admins or platform admins can remove members** — the API verifies this
+- **Cannot remove admins** — they must be demoted first (future feature)
+- **Cannot remove yourself**
+- **GitHub removal is best-effort** — if the caller's token lacks repo admin scope, GitHub removal may fail but Supabase/Neo4j cleanup still proceeds
+- **Never expose tokens** — all credential reads happen inside bash scripts