feat: Obsidian LLM wiki bootstrap (loops wiki/)

.cursor/rules/llm-wiki.mdc

@@ -0,0 +1,18 @@
+---
+description: LLM Wiki — read loops wiki/SCHEMA.md before any wiki operation
+globs:
+  - "loops wiki/**"
+alwaysApply: false
+---
+
+# LLM Wiki
+
+This project's Obsidian vault is **`loops wiki/`** (repository folder name + space + `wiki`).
+
+Before creating, updating, or querying wiki pages, read `loops wiki/SCHEMA.md` for conventions.
+
+The vault uses `[[wikilinks]]` for internal links. Every page has YAML frontmatter.
+
+When the user says "ingest", "add to wiki", "lint wiki", or "query wiki", follow the workflows in SCHEMA.md.
+
+After significant work sessions, suggest filing key decisions and learnings into the wiki (ADRs in `decisions/`, runbooks in `guides/`).

WIKI.md

@@ -0,0 +1,18 @@
+# Where is the LLM wiki?
+
+The Obsidian vault is **not** a folder named `wiki`.
+
+It lives at:
+
+**`loops wiki/`**
+
+There is a **space** between `loops` and `wiki` (project wiki naming rule: *repository folder name* + space + `wiki`).
+
+- **In Obsidian:** *Open folder as vault* → choose the `loops wiki` directory inside this repo.
+- **In Cursor / Explorer:** expand the repo root and look for **`loops wiki`** (not `wiki` alone).
+
+Start here: **`loops wiki/SCHEMA.md`**.
+
+**After `docs/` ingest:** see **`loops wiki/index.md`** → **Sources** for compiled markdown; originals remain under **`docs/`**.
+
+**Session memory:** dated breadcrumbs live in **`AI_SESSION_MEMORY.md`**; the wiki explains how that relates in **`loops wiki/memories/session-memory-in-wiki.md`**.

loops wiki/.obsidian/app.json

@@ -0,0 +1,9 @@
+{
+  "useMarkdownLinks": false,
+  "newLinkFormat": "shortest",
+  "strictLineBreaks": true,
+  "attachmentFolderPath": "assets",
+  "showFrontmatter": true,
+  "readableLineLength": true,
+  "defaultViewMode": "preview"
+}

loops wiki/SCHEMA.md

@@ -0,0 +1,154 @@
+# Wiki Schema
+
+> This file tells the LLM how to maintain this wiki. Read it at the start of every session that touches wiki pages.
+
+## Project
+
+- **Name**: loops
+- **Domain**: Portable workflow playbooks for AI coding agents in **Cursor** and **Claude Code**. Node.js 18+ repo with canonical loop definitions under `loops/`, a dispatcher router, personas, emit/install adapters, and optional LanceDB semantic search. Installed globally (`~/.loops`) or per-project (`.loops/`).
+
+## Directory structure
+
+The vault folder at the project root is **`loops wiki/`** (repository folder basename `loops`, a space, then `wiki`) — not bare `wiki/`.
+
+```
+loops wiki/
+├── SCHEMA.md          ← you are here (LLM instructions)
+├── index.md           ← content catalog, organized by type
+├── log.md             ← chronological operations log
+├── sources/           ← summaries of ingested documents
+├── entities/          ← concrete things (tools, services, APIs, tables, configs)
+├── concepts/          ← patterns, principles, architectural ideas
+├── decisions/         ← architecture decision records (ADRs)
+├── guides/            ← how-tos, runbooks, procedures
+├── memories/          ← session-memory mirrors / archives
+└── assets/            ← images, diagrams, attachments
+```
+
+## Page conventions
+
+### Filenames
+
+- **Kebab-case**, lowercase: `api-rate-limiting.md`, `postgres-connection-pool.md`
+- Singular nouns for entities: `redis-cache.md` not `redis-caches.md`
+- Verb-noun for guides: `deploy-to-production.md`, `rotate-api-keys.md`
+- Decisions use numbered prefix: `0001-use-postgres-over-mysql.md`
+
+### Frontmatter
+
+Every page MUST have YAML frontmatter:
+
+```yaml
+---
+title: Human-Readable Page Title
+type: source | entity | concept | decision | guide
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+tags: [relevant, tags]
+aliases: [alternate-name, abbreviation]
+sources: ["[[source-page]]"]
+status: active | draft | superseded | archived
+---
+```
+
+### Links
+
+Use Obsidian-style wikilinks exclusively:
+
+- `[[page-name]]` for standard links
+- `[[page-name|display text]]` for aliased links
+- `[[page-name#section]]` for section links
+- Never use markdown-style `[text](url)` for internal wiki links (reserve for external URLs)
+
+### Page structure
+
+Every page follows this skeleton:
+
+```markdown
+---
+(frontmatter)
+---
+
+# Title
+
+One-paragraph summary of what this page covers.
+
+## Content sections
+(varies by page type)
+
+## Related
+- [[linked-page-1]]
+- [[linked-page-2]]
+```
+
+## Page types
+
+### Source (`sources/`)
+
+Summary of an ingested document, article, file, or conversation.
+
+- **Key points** (bulleted takeaways)
+- **Detailed notes**
+- **Entities mentioned** — `[[wikilinks]]`
+- **Concepts discussed** — `[[wikilinks]]`
+
+### Entity (`entities/`)
+
+A concrete thing: tool, service, API, library, database, config.
+
+- **What it is** / **How it's used in this project** / **Key details** / **Related**
+
+### Concept (`concepts/`)
+
+A pattern, principle, or architectural idea.
+
+- **Definition** / **Application here** / **Tradeoffs** / **Related**
+
+### Decision (`decisions/`)
+
+ADR. Filename: `NNNN-short-title.md`.
+
+- **Status** / **Context** / **Decision** / **Consequences** / **Related**
+
+### Guide (`guides/`)
+
+How-to or runbook.
+
+- **Prerequisites** / **Steps** / **Troubleshooting** / **Related**
+
+## Operations
+
+### Obsidian (human viewer)
+
+Open the folder **`loops wiki/`** as a vault (Obsidian → Open folder as vault). Graph view and backlinks work with wikilinks.
+
+### Ingest
+
+When the user provides a new source: create `sources/…`, update entities/concepts/decisions/guides, refresh `index.md`, append `log.md`.
+
+### Ingest existing docs
+
+Migrate from repo **`docs/`** in batches; synthesize; do **not** delete original `docs/` without human sign-off.
+
+### Query
+
+Read `index.md`, then relevant pages; answer with `[[wikilinks]]`; offer to file synthesis as new pages.
+
+### Lint
+
+Orphans, dead links, index drift, stale frontmatter, thin pages — report as checklist; fix with user approval.
+
+## Style rules
+
+- Clear, direct prose. Prefer concrete paths, commands, and versions.
+- Use loops terminology consistently (loop, dispatcher, persona, emit, `LOOPS_ROOT`, `self_correcting`).
+- Update `updated` in frontmatter when editing a page.
+
+## Relationship to other project files
+
+- **`docs/`**: Raw documentation; ingest into `sources/` + derived pages. Binaries stay in `docs/`.
+- **`AI_SESSION_MEMORY.md`**: Session breadcrumbs; wiki is compiled long-form knowledge. See [[session-memory-in-wiki]].
+- **`MEMORY.md`**: Rolling two-section summary; not duplicated in the vault unless archived.
+- **`AGENTS.md`**: Agent index at repo root (currently bootstrap stub — fill in as the project matures).
+- **`README.md`**: Human-facing install and catalog; ingested into [[readme-project-overview]].
+- **SimpleMem / LanceDB**: Short recall layers; wiki is structured narrative. See [[lancedb-project-knowledge]].

loops wiki/concepts/loop-catalog.md

@@ -0,0 +1,51 @@
+---
+title: Loop catalog
+type: concept
+created: 2026-07-30
+updated: 2026-07-30
+tags: [loops, catalog, workflows]
+aliases: [workflows, loop-catalog]
+status: active
+---
+
+# Loop catalog
+
+## Definition
+
+The ten **workflow playbooks** plus the **dispatcher** meta-router. Canonical sources: `loops/<name>/loop.md` + `loop.yaml` under `LOOPS_ROOT` (`~/.loops` or project `.loops/`).
+
+## Application here
+
+| Loop | Use when the user wants to… | Self-correcting |
+|------|----------------------------|-----------------|
+| `plan-and-implement` | Design and build a feature, refactor, or non-trivial change | Yes |
+| `tdd` | Drive change by tests; lock behavior with a suite | Yes |
+| `sar` | Spec → attack with personas → repair; simplest correct | Yes |
+| `adversarial-gate` | Pre-merge review on PR or branch (max 3 rounds) | Yes |
+| `reproduce-and-fix` | Bug → minimal repro → failing test → fix → prove green | Yes |
+| `migrate` | Framework or version upgrade with checklist and rollback | Yes |
+| `explain-codebase` | Onboarding map of an unfamiliar repo | No |
+| `de-ai-ify` | Polish AI-sounding code; minimal-diff cleanup | Yes |
+| `swarm` | Full beginning-to-end ship pipeline (mega-loop) | Nested |
+| `use-the-loop` | Smallest composition when intent is ambiguous | Meta |
+
+**Dispatcher** (`dispatcher/loop.md`) is not in this table — it routes *to* these loops via [[loops-dispatcher]].
+
+### Invocation
+
+- Natural language: "write tests for the parser", "review this PR", "swarm this feature".
+- Claude Code slash commands: `/loops-dispatcher`, `/loops-tdd`, etc.
+- Cursor: awareness rule + emitted `loops-*` skills.
+
+## Tradeoffs
+
+- **Catalog vs custom:** loops are editable markdown — `node adapters/emit.js` after changes.
+- **Swarm vs single loop:** swarm chains phases; higher cost, full pipeline.
+- **use-the-loop:** safety valve for ambiguity; may chain 2 smaller loops.
+
+## Related
+
+- [[loops-dispatcher]]
+- [[loop-personas]]
+- [[self-correcting-contract]]
+- [[readme-project-overview]]

loops wiki/concepts/loop-personas.md

@@ -0,0 +1,55 @@
+---
+title: Loop personas
+type: concept
+created: 2026-07-30
+updated: 2026-07-30
+tags: [personas, review, adversarial]
+aliases: [personas]
+status: active
+---
+
+# Loop personas
+
+## Definition
+
+**Review lenses** — short role prompts the agent adopts for a step inside a loop. Canonical files: `LOOPS_ROOT/personas/<name>.md`. Personas are **not** top-level dispatcher options.
+
+## Application here
+
+### Catalog
+
+| Persona | Lens |
+|---------|------|
+| `skeptic` | Challenge problem statement and assumptions |
+| `security-auditor` | Trust boundaries, injection, authn/z, secrets |
+| `simplicity-advocate` | Removable complexity; simplest correct shape |
+| `perf-critic` | Hot paths, algorithmic waste, scale |
+| `regression-hunter` | Breakage for callers, migrations, behavior changes |
+| `edge-case-analyst` | Boundaries, empty/null, concurrency, malformed input |
+| `a11y-advocate` | Keyboard, focus, semantics, screen readers |
+| `api-contract-guardian` | Breaking changes, versioning, schema drift |
+| `dx-critic` | Errors, docs, onboarding friction, confusing APIs |
+
+### Used by (examples)
+
+| Loop | Persona usage |
+|------|---------------|
+| `sar` | Spec as skeptic; attack rotates security/simplicity/perf; judge bias simplicity |
+| `adversarial-gate` | Rounds: security → regression → edge-case; swap others when warranted |
+| `plan-and-implement` | Spec: simplicity + dx; Judge: regression-hunter |
+| `tdd` / `reproduce-and-fix` | Red/repro personas; Prove: regression-hunter |
+| `de-ai-ify` | Scan: simplicity-advocate; verify: regression-hunter |
+| `migrate` | Inventory: regression-hunter; plan: api-contract-guardian |
+
+**Contract:** `sar` and `adversarial-gate` must **Read** the persona file before adopting that lens — do not improvise from the name alone.
+
+## Tradeoffs
+
+- **Pro:** Structured adversarial review without a separate harness.
+- **Con:** Personas are frames, not execution ground truth — Judge still needs command output for code.
+
+## Related
+
+- [[loops-dispatcher]]
+- [[loop-catalog]]
+- [[self-correcting-contract]]

loops wiki/concepts/self-correcting-contract.md

@@ -0,0 +1,53 @@
+---
+title: Self-correcting contract
+type: concept
+created: 2026-07-30
+updated: 2026-07-30
+tags: [quality, builder-judge-manager, contract]
+aliases: [self-correcting, BJM]
+status: active
+---
+
+# Self-correcting contract
+
+## Definition
+
+A shared quality pattern for loops that produce shippable work. Canonical spec: `contracts/self-correcting.md`. Loops with `self_correcting: true` in `loop.yaml` adopt Builder → Judge → Manager roles with structured handoffs and **ground truth outside the Builder's reasoning**.
+
+## Application here
+
+| Role | Job | Does not |
+|------|-----|----------|
+| **Builder** | Produce deliverable; emit structured handoff | Mark task complete |
+| **Judge** | Evaluate against standard + independent ground truth | Rewrite deliverable |
+| **Manager** | Route DELIVER / REVISE / ESCALATE; own stop conditions | Improvise new quality bar mid-loop |
+
+**Loops using it (v0.1.4):** `plan-and-implement`, `tdd`, `reproduce-and-fix`, `sar`, `adversarial-gate`, `de-ai-ify`, `migrate`.
+
+**Skipped for:** typos, pure Q&A, map-only work (`explain-codebase`).
+
+### Ground truth examples
+
+| Task shape | Ground truth |
+|------------|--------------|
+| Code change | Test/lint output; diff vs task; tests not weakened |
+| Design | Written acceptance checks from spec |
+| Content polish | Brief + taxonomy; suite still green |
+| Upgrade | Checklist + verify commands + rollback ref |
+
+### Stop conditions (defaults)
+
+- `self_correcting_max_revisions: 3` — after 3rd failed Judge verdict, **ESCALATE** to user.
+- No "mostly passing" — all checklist items must PASS.
+
+## Tradeoffs
+
+- **Pro:** Separates producing from judging; prevents same-context rationalization.
+- **Pro:** Hard stop avoids infinite revise loops.
+- **Con:** More phases and tokens on non-trivial work — skip for trivial one-liners per loop guidance.
+
+## Related
+
+- [[model-classes]]
+- [[loop-catalog]]
+- [[loop-personas]]