From 369d8269c12d653862ad3ec5c98dd4ce53381b81 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Thu, 15 Oct 2026 18:35:58 +0200 Subject: [PATCH] docs: rewrite AGENTS.md and CLAUDE.md for the community edition The previous contract described the commercial release: tiers, Stripe, KVARK, the Windows Solo qualification gate and the hive-mind mirror sync. It told agents to preserve monetization, which the community edition removes. The new contract states the scope status of every package, the conversion rules, the build and verification commands and the working rules. CLAUDE.md now only adds Claude-specific notes. --- AGENTS.md | 835 +++++++++++++++--------------------------------------- CLAUDE.md | 742 ++---------------------------------------------- 2 files changed, 245 insertions(+), 1332 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eeeff43..03b379a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,699 +1,310 @@ -# AGENTS.md — Waggle OS -### Authoritative Operating Contract · All Agents · All Contributors · All Sessions +# AGENTS.md — Waggle Community Edition +### Operating contract for every agent and contributor on this branch -> Read this file in full before touching a single line of code. -> It is the single source of truth for architecture, strategic intent, and mechanical operating rules. -> If this file conflicts with any other document, **this file wins.** +> Read this file in full before changing code. +> On this branch it replaces the commercial-product contract. Where older documents under +> `docs/` (audits, briefs, launch and production-readiness records) disagree with this file +> or with the decision records in `docs/oss/adr/`, this file and the ADRs win. --- -## 0. How to Use This File +## 0. Where We Are -This file has two parts: **what the project is** (Sections 1-2) and **how to work on it** (Sections 3-9). -If you're about to write code, **Section 3** is the most important thing you'll read. +This branch turns the commercial Waggle OS codebase into an open-source **community edition**. +The conversion is in progress: the code still contains tiers, Stripe, KVARK, team mode and the +hive-mind memory substrate. Work packages remove or replace them one by one. + +Sources of truth, in order: +1. The agreed scope ("Waggle OSS Agreed Scope Annex", held by the project owner). +2. The decision records in [`docs/oss/adr/`](docs/oss/adr/README.md). +3. This file. + +Work is split into work packages: **0.x** preparation, **P0** unblocking, **P1** main scope, +**P2** hygiene and publication. Name the work package in commit messages when it helps +(for example `refactor(server): remove Stripe routes (P1.1)`). --- -## 1. What Waggle OS Actually Is +## 1. What the Community Edition Is -**Waggle OS** is a workspace-native AI agent platform with persistent memory. The active release -candidate is a Windows-first Tauri 2.0 desktop app with a Vite-bundled web UI and a bundled Node.js -sidecar. macOS packaging, signing, notarization, and runtime certification are roadmap work. +Waggle is a workspace-native AI agent platform with persistent memory: a web UI, a local +Fastify sidecar, an agent runtime with personas, skills and connectors. -**Strategic function:** Waggle is the demand-creation and qualification engine for KVARK — -Egzakta Group's sovereign enterprise AI platform. +The community edition: +- runs locally on Windows, macOS and Linux (the exact platform list awaits owner confirmation); +- installs with a Node-based installer (`packages/launcher`) and optional Tauri desktop + packages, without Python, Docker or a compiler on the user's machine; +- has no monetization: no tiers, trials, payments, license checks or upsell (ADR-0001); +- keeps memory on the user's machine through a memory contract backed by local mem0 (ADR-0002); +- sends analytics only after the user opts in (ADR-0006). -### Tiers (verified from `packages/shared/src/tiers.ts` — 4-tier: TRIAL/FREE(Solo)/TEAMS/ENTERPRISE, Solo-vs-Team collapse 2026-07-05) - -| Tier | Price | Purpose | -|---|---|---| -| TRIAL | $0 / 15 days | TEAM preview — 15 days of Team, then Solo | -| FREE (Solo) | $0 forever | Everything personal: unlimited workspaces+connectors, marketplace/custom skills, cloud embeddings, PDF/JSON export, basic audit — free forever | -| TEAMS | $49/mo per seat | Shared workspaces, WaggleDance, governance | -| ENTERPRISE | Consultative | KVARK sovereign on-prem (www.kvark.ai) | - -> PRO ($19/mo) was removed in the Solo-vs-Team collapse (2026-07-05); its -> capabilities folded into FREE (Solo). `TIER_LABELS` displays FREE as "Solo". - -**Moat strategy:** Memory + Harvest is free forever (lock-in moat). Agents, skills, -and connectors are all free (they generate memory). Team collaboration (shared memory, -WaggleDance, governance) is the upgrade trigger. - -### Current Release Qualification Contract (2026-08-22) - -- Launch gate: **Windows Solo only**. -- In-scope external-agent release cohort: **Claude Code, Codex, and Hermes**. Each integration - uses the user's own installed client and its official user authentication. -- **Cursor and OpenClaw are roadmap-only**: detection metadata may remain, but production launch, - hooks, Fleet/task dispatch, and direct run routes must fail closed for them. -- Claude Desktop, Codex Desktop, and Hermes Desktop may remain as detected convenience launch - surfaces; they are not separate memory-hook or agent-acceptance targets in this release gate. -- ChatGPT/OpenAI is a model/provider and memory-import surface, not a separate launcher target. -- The Windows Solo qualification receipt must prove the bundled Node sidecar, no-Python - OpenAI-compatible proxy, Waggle-managed local runtime/model, default in-process embedding path, - and freedom from developer Node, Docker, Python, external LiteLLM, or a separately installed - Ollama. A separate revision-bound receipt must prove smart-router primary, compact-tool-context, - budget, and fallback paths and may carry forward only under the launch recommendation's bounded - no-impact rule; user-installed Ollama remains optional. -- Persona release evidence requires a complete 10-persona x 3-run collection with every result - at or above 95/100 after any explicitly documented independent semantic adjudication, plus a - final-HEAD no-impact attestation or a fresh 30/30 rerun when intervening behavior changed. Never - relabel a non-gating collection as a canonical deterministic seal. -- Do not claim release approval until the current launch recommendation's exact-HEAD gates pass. -- Exact candidate revisions, installer hashes, local receipt hashes, carry-forward limits, and the - current verdict live only in `docs/production-readiness/09-LAUNCH_RECOMMENDATION.md`. Do not copy - an old candidate's evidence forward merely because a later branch contains its commits. -- Public GO still requires a publicly trusted Authenticode artifact and a sealed managed Deep - Security report for the exact approved release-tag commit, with no unresolved Critical/High. -- The repository remains private until an explicit open-source and licensing decision is made. - -### Key Technology Facts (Verified August 2026) +### Stack (verified 2026-10-15) | Layer | Stack | |---|---| -| Frontend | React **19** + TypeScript + Vite + Tailwind 4 + base-ui/react | -| Desktop | Tauri 2.0 (Rust shell) | -| Backend | Fastify sidecar (Node.js, bundled into Tauri) | -| LLM routing | Bundled no-Python OpenAI-compatible proxy for Windows Solo; optional LiteLLM deployment config | -| Database | SQLite via @waggle/core (better-sqlite3 + sqlite-vec-windows-x64) | -| Memory | FrameStore + HybridSearch + KnowledgeGraph + IdentityLayer + AwarenessLayer | -| Agent runtime | `packages/agent/src/agent-loop.ts` | -| Billing | Stripe (installed; `stripe@^21.0.1`) | -| Design | Hive DS — honey #e5a000 / hive-950 #08090c / accent #a78bfa | -| Tests | Vitest (unit) + Playwright (E2E) | -| Deploy | Windows Tauri installer; optional Dockerfile + docker-compose.production.yml + render.yaml | +| Web UI | React 19, TypeScript, Vite 6, Tailwind CSS 3.4, Radix UI primitives (`apps/web`) | +| Sidecar | Fastify on Node.js, run with tsx in development (`packages/server`) | +| Desktop shell | Tauri 2 (`app/src-tauri`), an optional wrapper around the sidecar and web UI | +| Database | SQLite via better-sqlite3 and sqlite-vec | +| Memory | Today the hive-mind substrate (`packages/hive-mind-core`); target is the memory contract plus local mem0 (P0.3, P1.5) | +| Local models | Waggle-managed Ollama runtime, or the user's own provider keys | +| Tests | Vitest (unit), Playwright (e2e and visual) | -Package manager: npm with the root `package-lock.json`. Source development requires Node -`^20.19.0 || >=22.12.0`; the packaged Windows desktop runtime is pinned to Node `22.23.2`. +npm workspaces with the root `package-lock.json`. Node `^20.19.0 || >=22.12.0`. --- -## 2. Repository Structure (Verified) +## 2. Repository Map and Scope Status -### Top level -``` -waggle-os/ -├── app/ # Tauri desktop shell (minimal React surface) -├── apps/ -│ ├── web/ # <-- MAIN web app UI (this is where most components live) -│ └── www/ # Landing page (waggle-os.ai) -├── packages/ # 28 workspace packages (see below) -├── sidecar/ # Node.js sidecar bundled into Tauri -├── scripts/ # build-sidecar, bundle-native-deps, bundle-node -├── tests/ # Cross-cutting integration tests -├── docs/ # ARCHITECTURE.md and others -├── cowork/ # Scratchpad / planning / handoff docs (historical; AGENTS.md promoted to root) -├── .planning/ .scratch/ .mind/ # Working notes -├── docker-compose.yml + .production.yml + Dockerfile + render.yaml -├── litellm-config.yaml # LLM router config -├── playwright.config.ts + playwright-e2e.config.ts -├── vitest.config.ts + vitest.setup.ts -└── package.json (workspaces: apps/*, packages/*) -``` +| Path | Status in the community edition | +|---|---| +| `apps/web` | Keep. The main UI; all React code lives here. | +| `app/` | Keep. Tauri shell only (there is no `app/src/`). | +| `packages/agent`, `core`, `server`, `shared`, `sdk`, `weaver`, `marketplace`, `cli`, `launcher` | Keep. | +| `packages/waggle-dance`, `packages/worker` | Postponed: team mode stays in the repo, is not built or shipped (ADR-0003). | +| `packages/optimizer` | Excluded: part of self-learning (ADR-0004). Removed in P1.4. | +| `packages/hive-mind-*`, `memory-mcp`, `wiki-compiler` | Excluded once P1.5 moves all memory access to the contract. | +| `packages/admin-web`, `apps/www` | Excluded. | +| `apps/browser-ext` | Not decided. Do not extend it. | +| `sidecar/`, `benchmarks/`, `judging/`, most of `docs/` | Internal history of the commercial product, removed in P2.2. Community-edition docs live in `docs/oss/`. | -### Packages (`packages/`, 28 workspaces — verified 2026-08-02) -``` -Core (15): -admin-web cli launcher marketplace -agent core memory-mcp optimizer -sdk server shared waggle-dance -weaver wiki-compiler worker +### Where things live -hive-mind OSS source set (13 — curated forward-port target is marolinik/hive-mind; see §7.5): -hive-mind-core hive-mind-cli hive-mind-shim-core hive-mind-mcp-server -hive-mind-wiki-compiler hive-mind-hooks-core -hive-mind-hooks-{claude-code, claude-desktop, codex, codex-desktop, - cursor, hermes, openclaw} -``` -> Note: the prior list said "16" and included `ui`, which has no `package.json` -> (not a workspace). The live count is 28: 15 product packages and 13 -> `hive-mind-*` packages. - -### `packages/agent/src/` — MOST ACTIVE (94 .ts files + 4 subdirs) - -Key files (not exhaustive — grep before creating anything new): -``` -agent-loop.ts Core execution loop -orchestrator.ts buildSystemPrompt(), recallMemory() -personas.ts AgentPersona interface + logic (data split out) -persona-data.ts Pure PERSONAS declarative data array -custom-personas.ts loadCustomPersonas() from disk -behavioral-spec.ts BEHAVIORAL_SPEC rules -tool-filter.ts filterToolsForContext() -injection-scanner.ts scanForInjection() — 3 pattern sets -cost-tracker.ts CostTracker + model pricing -skill-frontmatter.ts parseSkillFrontmatter() -kvark-tools.ts kvark_search, kvark_ask_document (tier-gated) -feature-flags.ts EXISTS — don't recreate -subagent-orchestrator.ts Subagent spawn/coord -workflow-composer.ts -workflow-harness.ts -workflow-templates.ts - -Evolution subsystem: - evolution-orchestrator.ts evolution-deploy.ts evolution-gates.ts - evolution-llm-wiring.ts evolve-schema.ts iterative-optimizer.ts - judge.ts eval-dataset.ts compose-evolution.ts - -Capability & trust: - capability-acquisition.ts capability-router.ts trust-model.ts - permissions.ts credential-pool.ts confirmation.ts - -Quality & correction: - quality-controller.ts contradiction-detector.ts - correction-detector.ts improvement-detector.ts improvement-wiring.ts - loop-guard.ts iteration-budget.ts - -Subdirs: - commands/ connectors/ mcp/ providers/ -``` - -### `packages/core/src/` -``` -Top-level: config.ts, cron-store.ts, file-store.ts, install-audit.ts, - logger.ts (createCoreLogger), memory-import.ts, migration.ts, - multi-mind.ts, multi-mind-cache.ts, optimization-log.ts, - skill-hashes.ts, team-sync.ts, telemetry.ts, vault.ts, - workspace-config.ts, index.ts - -Subdirs: - compliance/ — compliance reporting, interaction-store, status-checker - -MOVED (2026-04-30 monorepo migration): the memory substrate `mind/` (db/schema/ - identity/awareness/frames/sessions/search/knowledge/scoring/reconcile/ontology/ - concept-tracker/entity-normalizer/evolution-runs/execution-traces/ - improvement-signals/embedding-provider/*-embedder) and `harvest/` (chatgpt/claude/ - claude-code/gemini/perplexity/pdf/plaintext/markdown/url/universal adapters + - pipeline.ts + dedup.ts) now live at **packages/hive-mind-core/src/{mind,harvest}/**, - NOT under packages/core/. The OSS mirror is curated from there through a maintainer-reviewed - forward-port (§7.5); raw subtree branches are never publish sources. -``` - -For the deep-dive on what the mind/ substrate does, see [`docs/memory-architecture.md`](docs/memory-architecture.md). - -### `packages/shared/src/` -``` -types.ts User, Team, AgentDef, Task, WaggleMessage -constants.ts Team roles, job statuses -schemas.ts Zod schemas -tiers.ts TIERS + TierCapabilities (canonical 4-tier: TRIAL/FREE(Solo)/TEAMS/ENTERPRISE) + TIER_LABELS/tierLabel -mcp-catalog.ts MCP server catalog -index.ts Barrel -``` - -### `app/` (Tauri desktop shell) -``` -app/src-tauri/ # Rust shell + capabilities/ + tauri.conf.json -app/scripts/ # build/installer/signing TS tooling (tauri-tsc gate target) -``` - -**Note:** `app/` is now the Tauri Rust shell only — there is no `app/src/`. The -React cockpit UI moved to `apps/web` long ago; the desktop binary loads the -`apps/web` dist. All React UI lives in `apps/web/src/`. - -### `apps/web/src/` (MAIN UI) ``` apps/web/src/ -├── assets/ components/ hooks/ lib/ -├── pages/ providers/ test/ +├── components/os/apps/ # per-app UI shells +├── components/os/overlays/ # OnboardingWizard.tsx, PersonaSwitcher.tsx +├── components/ui/ # shared UI primitives +└── lib/ hooks/ providers/ pages/ test/ -components/ -├── os/ -│ ├── apps/ # Per-app UI shells -│ └── overlays/ # OnboardingWizard.tsx, PersonaSwitcher.tsx live HERE -└── ui/ # Shared UI primitives +packages/agent/src/ # most active package; grep before creating anything + agent-loop.ts core execution loop + orchestrator.ts buildSystemPrompt(), recallMemory() + personas.ts, persona-data.ts, custom-personas.ts + behavioral-spec.ts BEHAVIORAL_SPEC rules + tool-filter.ts filterToolsForContext() + injection-scanner.ts scanForInjection() + cost-tracker.ts CostTracker and model pricing (stays, ADR-0004) + feature-flags.ts exists; do not recreate + commands/ connectors/ mcp/ providers/ + +packages/server/src/local/ # the local sidecar: index.ts, routes/, services/ +packages/core/src/ # config, cron-store, file-store, vault, logger, telemetry +packages/shared/src/ # shared types, Zod schemas, MCP catalog ``` -### Build Commands (verified from `package.json`) -```bash -npm run dev # Vite dev server (apps/web) -npm run build # Vite build to /dist (apps/web) -npm run build:packages # tsc --build: shared -> core -> agent -> server (order matters) -npm run build:all # Packages then web -npm run lint # ESLint repo-wide -npm run test # Vitest unit tests -npm run test:e2e # Playwright API tests -npm run test:visual # Playwright visual regression -npm run test:all # Full Playwright -``` - -### Verification Commands (run these, don't claim "it compiles") -```bash -npx tsc --noEmit --project packages/agent/tsconfig.json -npx tsc --noEmit --project packages/server/tsconfig.json # sidecar — runs via tsx (transpile-only), so NOT typechecked by `npm run build` -npx tsc --noEmit --project app/tsconfig.json -npm run test -- --run -npm run lint -``` -> `npm run build` typechecks **only `apps/web`**. The Fastify sidecar runs via -> `tsx` (transpile-only) — server-route type errors ship undetected unless you -> run the `packages/server` tsc above. (A real type error slipped through this -> way on 2026-05-28; see `docs/addictiveness-audit-2026-05-28/REDUNDANCY-AUDIT.md`.) - -### Windows Solo release commands (PowerShell 7; frozen clean checkout) - -```powershell -# Local build-host preparation (the installed desktop has none of these prerequisites). -npm ci -npm ci --prefix app --ignore-scripts -npm run build:packages - -# Local unsigned smoke build only; this is not a releasable artifact. -npm --prefix app run tauri:build:win - -# Optional internal-pilot build. Its private test root is not public trust. -npm --prefix app run tauri:build:win:pilot-signed - -# Certify an internal candidate under a disposable Windows profile. -pwsh -NoProfile -File scripts/certify-windows-installer.ps1 ` - -InstallerPath "" ` - -ExpectedSourceRevision "<40-character-final-HEAD>" ` - -VerifyManagedModel -``` - -Production signing is hosted-only. Do not use a local thumbprint, client secret, or -`sign-windows-artifact.ps1` substitute to create a release artifact. The exact-tag -`.github/workflows/release.yml` Azure OIDC chain is authoritative for production signing, -certification, attestation, and publication. Never treat an unsigned or internal-pilot build -as publicly trusted. -The certified installed desktop must not depend on developer Node.js, Python, -Docker, external LiteLLM, or a separately installed Ollama. +To be removed by work packages, so do not build on them: `packages/shared/src/tiers.ts` +(P0.1), `packages/agent/src/kvark-tools.ts` and the evolution / improvement / correction +modules (P1.4), `packages/server/src/stripe/` and `packages/server/src/kvark/` (P1.1), +`packages/core/src/compliance/` and `install-audit.ts` (P1.2). --- -## 3. Behavioral Rules — How You Must Work +## 3. Conversion Rules -These rules apply to every code change. They exist because violations have cost real debugging time. +=== CRITICAL === +1. **No monetization.** Do not add tier checks, trials, prices, payment flows, license + checks, or KVARK and Team upsell. When a work package touches such code, remove it. + The word "tier" also means UserTier (UI complexity), ModelTier, persona tiers, CLI levels + and memory health levels. Leave those alone and never mass-replace the word. +2. **Memory goes through the contract.** New code must not import `@waggle/hive-mind-*`, + `memory-mcp` or `wiki-compiler`, and must not run SQL against the memory database. Until + the contract lands (P0.3), keep memory changes minimal. The knowledge graph is not in v1. +3. **Team mode is frozen.** Do not add features to team routes, WaggleDance or the worker. +4. **Self-learning is out.** Do not extend evolution, improvement signals, correction + learning, judge or eval loops, or `optimizer`. Cost tracking stays. +5. **Licenses.** Every new dependency must be compatible with MIT distribution. No GPL or + AGPL code in shipped artifacts: this is why Baileys (GPL `libsignal`) is replaced by + `whatsapp-web.js` (ADR-0005). State the license of a new dependency in the commit message. +6. **Analytics are opt-in.** Nothing is sent before the user agrees. The PostHog key comes + only from the build environment (`VITE_POSTHOG_KEY`) and is never committed. +7. **Three operating systems.** Every platform-specific branch needs Windows, macOS and Linux + paths. End users must not need Python, Docker, a compiler or a developer Node install. +8. **Secrets and history.** Never commit secrets. Never push this repository's history to a + public remote: the public release is a fresh repository built from the cleaned tree (P2.6). +9. **Upstream defects.** When you find or fix a defect that also exists in the commercial + product, log it in [`docs/oss/upstream-fixes.md`](docs/oss/upstream-fixes.md) in the same + commit, in English, using the template at the top of that file. Scope removals (tiers, + Stripe, KVARK, team mode) are not defects and are not logged. +=== END CRITICAL === -### 3.1 Think Before Coding +--- + +## 4. Build, Run and Verify + +### Setup and run + +```bash +npm ci +npm run build:packages # required: workspace packages export dist/, the sidecar fails without it +npm run build # typechecks apps/web, builds it into the root dist/ (emptied first) +npm run dev:server # sidecar on http://localhost:3333, serves the UI from the root dist/ +``` + +- The sidecar registers routes for the files in `dist/` when it starts (`@fastify/static` + with `wildcard: false`), so assets from a later build return 404. Restart the sidecar after + `npm run build`. +- `npm run dev:web` (Vite) cannot authenticate against the sidecar today (UF-003). Use the + UI served by the sidecar. + +### Verification (run these, do not claim "it compiles") + +```bash +npx tsc --noEmit --project packages/agent/tsconfig.json +npx tsc --noEmit --project packages/server/tsconfig.json # the sidecar runs via tsx, so nothing else typechecks it +npx tsc --noEmit --project app/tsconfig.json +npm run test # root Vitest: packages, tests/, scripts/ (excludes apps/**) +(cd apps/web && npx vitest run) # web UI tests use their own config +npm run lint +``` + +- Playwright e2e reuses any server already listening on :3333 and its data directory. For an + isolated run set `WAGGLE_E2E_REUSE_EXISTING_SERVER=0` and a free `WAGGLE_E2E_PORT`. Its web + server step runs `npm run build:all`, which rewrites the root `dist/`. +- [`docs/oss/baseline.md`](docs/oss/baseline.md) records the build, typecheck, lint and test + results at the start of the conversion. Compare your results against it and do not let a + green check turn red. + +--- + +## 5. How to Work + +### 5.1 Think before coding **Don't assume. Don't hide confusion. Surface tradeoffs.** -Before implementing anything: - State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them — don't pick silently. +- If multiple interpretations exist, present them; don't pick silently. - If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. +- If something is unclear, stop, name what's confusing, and ask. === CRITICAL === -The single most expensive LLM failure mode is making wrong assumptions and building -100+ lines on top of them. The fix costs 10x what the question would have cost. -Stop. Ask. Then build. +The most expensive failure mode is making a wrong assumption and building 100+ lines on top +of it. The fix costs ten times what the question would have cost. Stop. Ask. Then build. === END CRITICAL === -### 3.2 Simplicity First +### 5.2 Simplicity first -**Minimum code that solves the problem. Nothing speculative.** +Minimum code that solves the problem. No features beyond the request, no abstractions for +single-use code, no configurability nobody asked for, no error handling for impossible +scenarios. If you write 200 lines and it could be 50, rewrite it. -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. +### 5.3 Surgical changes -Test: **"Would a senior engineer say this is overcomplicated?"** If yes, simplify. +- Touch only what the task needs. Don't reformat or "improve" adjacent code. +- Match the existing style. +- If you notice unrelated dead code, mention it; don't delete it. +- Remove imports, variables and functions that your own change made unused. -### 3.3 Surgical Changes +Every changed line should trace to the request. Removals required by a work package are the +request. -**Touch only what you must. Clean up only your own mess.** +### 5.4 Goal-driven execution -When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, **mention it** — don't delete it. +Turn tasks into verifiable goals ("fix the bug" becomes "write a test that reproduces it, then +make it pass"). For multi-step work, state a short plan with a check per step. A task is not +done until verification passes. -When your changes create orphans: -- Remove imports/variables/functions YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. +### 5.5 Context discipline -Test: **Every changed line should trace directly to the request.** +- Re-read a file before editing it if the conversation has moved on. Do not trust memory. +- Read files over 500 lines in chunks; never assume you saw all of it. +- Tool output over ~50k characters is truncated. If results look sparse, narrow the query. +- On a rename or removal, grep for direct references, types, string literals, dynamic + imports, barrel re-exports and tests. One grep is never enough. -### 3.4 Goal-Driven Execution +### 5.6 Check before create -**Define success criteria. Loop until verified.** +Grep before adding a file. If something might already exist, it probably does (see section 9). -Transform vague tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" +### 5.7 Output discipline -For multi-step tasks, state a brief plan: -``` -1. [Step] -> verify: [check] -2. [Step] -> verify: [check] -3. [Step] -> verify: [check] -``` - -A task is not done until verification passes. "I think this works" is not verification. - -### 3.5 Context Discipline - -- **Context decay:** After 10+ messages, re-read any file before editing. Do not trust memory. -- **File read budget:** Files >500 LOC require chunked reads. Never assume complete view. -- **Truncation:** Tool results >50k chars are silently truncated. If sparse, re-run narrower. -- **Re-read before edit. Re-read after edit.** Max 3 edits per file before verification read. -- **Exhaustive grep on rename:** Direct refs, type-level, string literals, dynamic imports, - re-exports/barrel entries, test files. **One grep is never enough.** - -### 3.6 Check Before Create - -Before adding a new file, **grep first.** The repo has ~94 files in `packages/agent/src` -alone. If you're about to write something that might already exist, it probably does. -See Section 8 for known utilities. - -### 3.7 Output Discipline - -- **Chat reply budget.** Long specs, handoffs, audit reports, and multi-phase plans MUST - be written to files (memory/, docs/, or via `/handoff`), not rendered inline. The chat - is a pointer; the file is the deliverable. -- **Chunk long work.** Multi-phase roadmaps and >1k-line specs: implement in phases, - commit per phase, give a 3-line status, then stop and await the next instruction. Do - not stream an exhaustive summary that blows the output budget. -- **Rationale:** 13+ prior sessions were lost mid-response to the 500-output-token cap. - Surface shortly, persist richly. - -### 3.8 Handoff Discipline - -- **Use the skill.** End-of-session handoffs invoke `~/.Codex/skills/handoff/`, which - enforces verification (`git status`, tests N/M, `npx tsc --noEmit` on touched packages) - BEFORE writing the doc. Do not hand-write handoffs that skip the gate. -- **Canonical location.** Handoffs live at - `C:/Users/MarkoMarkovic/.Codex/projects/D--Projects-waggle-os/memory/project_session_handoff__s.md`, - with the memory-dir MEMORY.md "START HERE" pointer updated. That is the single source - of truth for what shipped / what's left / how to roll back. -- **Never hide failures.** Failing tests, unverified MCP reconnects, wrong build dir — - surface under "What's still open" in the handoff. Clean-looking handoffs that hide rot - cost the next session hours. +- Long specs, plans and reports go into files under `docs/oss/`, not into chat. +- Implement large work in phases: commit per phase, report briefly, then continue. +- Never hide failures. Report failing tests and skipped checks with their output. --- -## 4. Pre-Work Protocol +## 6. Pre-Work Protocol -Before any structural refactor on a file >300 LOC: -1. Remove dead props, unused exports, unused imports, `console.log`. -2. Commit separately: `chore(scope): dead code removal — [filename]` - -**Phased execution:** Max 5 files per phase. Complete → verify → await approval → next phase. - -**Senior dev override:** If architecture is flawed, state is duplicated, or patterns -are inconsistent — state it and propose a fix. Standard: *"What would a senior engineer -reject in review?"* +- Before a structural refactor of a file over 300 lines, remove dead code in a separate + commit: `chore(scope): dead code removal — `. +- Work in phases of at most five files: change, verify, then continue. +- If the architecture is flawed, state is duplicated, or patterns are inconsistent, say so + and propose a fix. Standard: what would a senior engineer reject in review? --- -## 5. Persona Architecture +## 7. Personas and Onboarding -### Shipped (22 personas — data in `persona-data.ts`, logic in `personas.ts`) -The original 13 + 4 universal/orchestration + 5 domain personas all shipped. -The PersonaSwitcher groups them into **two tiers** (`apps/web/src/lib/persona-tier.ts`): +- `packages/agent/src/persona-data.ts` holds the canonical `PERSONAS` array (pure data); + `personas.ts` holds the `AgentPersona` interface and logic. +- The PersonaSwitcher (`apps/web/src/components/os/overlays/PersonaSwitcher.tsx`) groups + personas into universal modes and template-scoped specialists (`apps/web/src/lib/persona-tier.ts`). +- The OnboardingWizard (`apps/web/src/components/os/overlays/OnboardingWizard.tsx`) runs + first-launch → who-are-you → model-gate → memory-import → template → first-task. Templates + and the template-to-persona mapping live in `overlays/onboarding/constants.ts`. -**Universal Modes (8 — always available in every workspace):** -general-purpose, planner, verifier, coordinator, researcher, writer, analyst, coder -- **general-purpose** — versatile default, full tool access -- **planner** — read-only strategic planning, no file writes (`isReadOnly`) -- **verifier** — adversarial QA, read-only, VERDICT output format (`isReadOnly`) -- **coordinator** — pure orchestrator, spawn/list/get_agent_result only (gated by `FEATURE_FLAGS.COORDINATOR_MODE`) - -**Specialists (14 — template-scoped via `TEMPLATE_SPECIALISTS`):** -project-manager, executive-assistant, sales-rep, marketer, product-manager-senior, -hr-manager, legal-professional, finance-owner, consultant, support-agent, -ops-manager, data-engineer, recruiter, creative-director - -> Note: the onboarding picker (`onboarding/constants.ts` → `ALL_ONBOARDING_PERSONAS`) -> intentionally surfaces only **19** of the 22 — it omits planner/verifier/coordinator -> (read-only/orchestration modes don't make sense as a workspace's *starting* brain) and -> uses its own 3-way grouping (universal/knowledge/domain). Same canonical personas, a -> different view for a different UI moment. `persona-data.ts` is the single source of truth. - -**Split is done:** `persona-data.ts` holds the pure `PERSONAS` array; -`personas.ts` exports the `AgentPersona` interface and logic only. - -### AgentPersona Interface — Shipped Fields (verified `personas.ts`) ```typescript interface AgentPersona { - // core id, name, description, icon, systemPrompt, modelPreference, tools: string[], workspaceAffinity: string[], suggestedCommands: string[], defaultWorkflow: string | null, - // guardrails + picker metadata (all optional, all shipped) - disallowedTools?: string[] // denylist — overrides tools[] on conflict - failurePatterns?: string[] // documented failure modes — shown in hover tooltip - isReadOnly?: boolean // true = no write tools after applyPersonaToolFilter/filterMcpToolsForPersona - tagline?: string // one sentence for picker hover - bestFor?: string[] // 3 example tasks in user-facing language - wontDo?: string // hard boundary statement - suggestedSkills?: string[] // installable from marketplace - suggestedConnectors?: string[] // connector IDs - suggestedMcpServers?: string[] // MCP server names from mcp-registry + disallowedTools?: string[] // denylist, wins over tools[] + failurePatterns?: string[] + isReadOnly?: boolean // no write tools after persona tool filtering + tagline?: string + bestFor?: string[] + wontDo?: string + suggestedSkills?: string[] + suggestedConnectors?: string[] + suggestedMcpServers?: string[] } ``` --- -## 6. Onboarding & PersonaSwitcher (correct paths) +## 8. Security Constraints (Non-Negotiable) -### OnboardingWizard -**Path:** `apps/web/src/components/os/overlays/OnboardingWizard.tsx` -(NOT `app/src/components/onboarding/` — that path doesn't exist.) - -Shipped: 6-step flow (`first-launch → who-are-you → model-gate → memory-import → -template → first-task`). The 15 TEMPLATES + the `TEMPLATE_PERSONA` mapping (template → -one default persona id) live in `overlays/onboarding/constants.ts`, wired to the -canonical persona ids from `persona-data.ts`. The wizard surfaces a **curated 6** of the -15 (`CURATED_ONBOARDING_TEMPLATES`) for the ≤2-min flow; the full 15 are reachable from -the workspace gallery later. (Picker persona roster = `ALL_ONBOARDING_PERSONAS`, the -19-of-22 view noted in §5.) - -### PersonaSwitcher -**Path:** `apps/web/src/components/os/overlays/PersonaSwitcher.tsx` - -Shipped (M-01): Two-tier layout — "UNIVERSAL MODES" (8, from `UNIVERSAL_MODE_IDS`) + -"YOUR WORKSPACE SPECIALISTS" (template-scoped via `getSpecialistsForTemplate` in -`lib/persona-tier.ts`). Hover tooltip (`buildPersonaTooltip`, `lib/persona-tooltip.ts`) -shows tagline + bestFor + wontDo. "Create Custom Persona" inline form POSTs to -`/api/personas`. +1. **Secrets** belong in the secret store (`packages/core/src/vault.ts` until P1.2 replaces + it with a `SecretStore` interface) or an untracked local `.env`. Never in git. `.env.example` + holds placeholders only. +2. **Injection defense.** Call `scanForInjection()` from `injection-scanner.ts` on all + connector and external input. +3. **No eval and no dynamic require.** +4. **Tauri IPC allowlist** stays explicit in `app/src-tauri/capabilities/`. +5. **Parameterized SQL only.** No string interpolation in queries. --- -## 7. Security Constraints (Non-Negotiable) - -1. **Vault-only secrets.** API keys belong in Vault or an untracked local `.env`, never in Git. `.env.example` may contain non-secret development defaults, but never usable credentials or secrets. -2. **Injection defense.** `scanForInjection()` from `injection-scanner.ts` MUST be called on all connector/external input. -3. **No eval, no dynamic require.** Tauri WebView is restricted. -4. **Tauri IPC allowlist.** Explicit in `app/src-tauri/capabilities/`. Never `allowlist: all: true`. -5. **Parameterized queries.** No string interpolation in SQL. Ever. better-sqlite3 supports parameters. -6. **KVARK contact data.** Submits to your API only — no third-party form services. -7. **Secrets in `packages/core/src/vault.ts`** — use it; don't build parallel secret stores. - ---- - -## 7.5. Memory Substrate Sync (waggle-os → hive-mind, curated forward-port) - -The memory substrate lives at **`packages/hive-mind-core/src/{mind,harvest}/`** (moved from -`packages/core/src/` in the 2026-04-30 monorepo migration). The public OSS mirror at -[`marolinik/hive-mind`](https://github.com/marolinik/hive-mind) is **generated FROM** this monorepo -via a **maintainer-curated forward-port** (NOT a mechanical `git subtree split` — see the -correction below). The mirror uses its own curated layout (`packages/core`, co-located tests, -rewritten imports) and **excludes** Waggle-proprietary content (see the exclusion list below). - -=== CRITICAL — sync policy (founder-ratified 2026-06-11) === -**The monorepo is the SOLE source of truth for the substrate. Never author substrate features -directly on the OSS mirror.** Parity is NOT automatic — it broke once: the cross-encoder reranker -(`inprocess-reranker.ts` + HybridSearch options) was written directly on `marolinik/hive-mind` -during the LoCoMo benchmark arc and existed ONLY there, discovered by the W4 recon and -reverse-ported in W4.2 (`f47ee8f`). Rules: -1. Substrate changes land in `packages/hive-mind-core/` here FIRST; the mirror is updated - through a reviewed, maintainer-curated forward-port afterward. -2. Benchmark/experiment work in a `D:/Projects/hive-mind` checkout is throwaway unless - reverse-ported here — port it the same arc, don't let it sit. -3. Run **`node scripts/oss-drift-check.mjs D:/Projects/hive-mind`** before every OSS release - push and after any arc that touched a hive-mind checkout. The checker compares the live - mapped trees with an immutable reviewed baseline: parity and reviewed adaptations are - allowed, while known blockers, unreviewed differences, or forbidden exports keep exit 1. -4. External PRs on the OSS repo are fine — the maintainer intentionally ports accepted changes - back here first, then prepares the next curated forward-port. -=== END CRITICAL === - -=== CORRECTION — how the sync ACTUALLY works (2026-06-12 drift analysis) === -The prior text here claimed the mirror is produced by `scripts/oss-subtree-split.sh` and that a -"subtree-split filter" handles the must-not-export files. **Both were false** (verified -2026-06-12, `docs/ux-refactor/oss-sync-finding-2026-06-12.md`): -- `scripts/oss-subtree-split.sh` produces RAW per-package branches with the WRONG layout - (`packages/hive-mind-core`, not the mirror's `packages/core`) and **no file filter ever - existed**. A raw split + push would have **leaked proprietary IP**. The script now carries a - hard ABORT guard (refuses to emit a branch containing the proprietary files) + a deprecation - header; it is for inspection / as a curation starting point ONLY, never a direct push source. -- **The real sync is a hand-curated forward-port** onto a maintainer feature branch in the OSS - clone (e.g. `feature/mono-parity-YYYY-MM-DD`): adapt the layout, rewrite imports, and STRIP the - excluded content. That curation — not a filter — is what keeps proprietary content out. - -**OSS-EXCLUDED (must NOT reach the public mirror):** -- Files: `vault.ts`, `evolution-runs.ts`, `execution-traces.ts`, `improvement-signals.ts`, - `compliance/**` (vault/compliance live in `@waggle/core`; the other three are barrel-exported - from `hive-mind-core` but stripped on export). Enforced by the script's abort guard. -- **Interleaved:** the `install_audit` table DDL + its rebuild migration inside - `mind/{schema.ts,db.ts}` are ALSO excluded (capability-install trust trail / EU-AI-Act - compliance — Waggle governance, not generic substrate). A file filter cannot catch this; only - the curated edit strips it. **Consequence:** substrate changes confined to `install_audit` - (e.g. P5/D4 `'uninstalled'`, #15 `trust_source` CHECK) have **nowhere to land on the mirror — - do NOT treat them as a pending OSS port.** -=== END CORRECTION === - -**To work on the substrate or publish the OSS mirror:** see -[`packages/hive-mind-core/CONTRIBUTING.md`](./packages/hive-mind-core/CONTRIBUTING.md), -[`scripts/oss-subtree-split.sh`](./scripts/oss-subtree-split.sh) (inspection/guard only), and -[`scripts/oss-drift-check.mjs`](./scripts/oss-drift-check.mjs) (run before every release; its -immutable baseline distinguishes parity, reviewed adaptations, known blockers, unreviewed -differences, and forbidden exports; every blocker or unreviewed entry must be resolved or -explicitly re-baselined through maintainer review before an OSS release). - -**Deprecated (do not rely on; do not delete):** the old dual-repo bidirectional-sync workflows -`.github/workflows/{mind-parity-check,sync-mind}.yml` and the `.github/sync.md` manual are **preserved -as deprecation anchors** from when the substrate was duplicated across two repos. Their trigger paths -(`packages/core/src/{mind,harvest}/**`) no longer exist, so they never fire; each carries a DEPRECATED -header explaining the migration. Leave them in place for audit trail. - ---- - -## 8. Already Built — Do Not Recreate - -Grep before creating. These exist and are functional: +## 9. Already Built — Do Not Recreate | File | What it does | |---|---| -| `packages/agent/src/injection-scanner.ts` | `scanForInjection()` — 3 pattern sets | -| `packages/agent/src/cost-tracker.ts` | `CostTracker` + model pricing table | -| `packages/agent/src/tool-filter.ts` | `filterToolsForContext()` — allowlist/denylist | -| `packages/agent/src/skill-frontmatter.ts` | `parseSkillFrontmatter()`, `ParsedSkill` | -| `packages/agent/src/kvark-tools.ts` | `kvark_search`, `kvark_ask_document` (tier-gated) | -| `packages/agent/src/feature-flags.ts` | **EXISTS** — don't create | -| `packages/agent/src/persona-data.ts` | Canonical `PERSONAS` array (pure data) | -| `packages/agent/src/custom-personas.ts` | `loadCustomPersonas()` from disk | -| `packages/agent/src/judge.ts` | Evolution judging | -| `packages/agent/src/iterative-optimizer.ts` | Self-improvement loop | +| `packages/agent/src/injection-scanner.ts` | `scanForInjection()` | +| `packages/agent/src/cost-tracker.ts` | `CostTracker` and model pricing | +| `packages/agent/src/tool-filter.ts` | `filterToolsForContext()` | +| `packages/agent/src/skill-frontmatter.ts` | `parseSkillFrontmatter()` | +| `packages/agent/src/feature-flags.ts` | Feature flags | | `packages/agent/src/capability-router.ts` | Per-capability routing | -| `packages/agent/src/loop-guard.ts` | Infinite loop prevention | +| `packages/agent/src/loop-guard.ts` | Infinite-loop prevention | | `packages/agent/src/contradiction-detector.ts` | Memory conflict detection | -| `packages/shared/src/tiers.ts` | `TIERS`, `TierCapabilities` — canonical tier system | | `packages/shared/src/mcp-catalog.ts` | MCP server catalog | -| `packages/core/src/vault.ts` | Secret storage | -| `packages/core/src/telemetry.ts` | Telemetry pipeline | -| `packages/hive-mind-core/src/harvest/pipeline.ts` | Harvest adapters + dedup | -| `packages/core/src/compliance/` | Compliance + audit | -| `apps/web/src/components/os/` | Main desktop cockpit UI loaded by Tauri | +| `packages/core/src/telemetry.ts` | Local telemetry pipeline | +| `packages/server/src/local/persona-tool-filter.ts` | `applyPersonaToolFilter`, `filterMcpToolsForPersona` | --- -## 9. KVARK Integration +## 10. Glossary -**Canonical copy:** -> "Everything Waggle does — on your infrastructure, connected to all your internal systems. -> Full data pipeline injection, your permissions, complete audit trail, governance. -> Your data never leaves your perimeter." - -**URLs (hardcoded only in `kvark-tools.ts` and `KvarkNudge` component):** -- Product site: https://www.kvark.ai -- License server: https://license.waggle-os.ai/validate -- SaaS cloud: https://cloud.waggle-os.ai - -`kvark-tools.ts` gates `kvark_search` and `kvark_ask_document` to TEAMS/ENTERPRISE tiers. -Do not recreate or expose outside gating. - ---- - -## 10. Sprint Status (May 2026) - -### What Landed -**April 2026 baseline:** -- `tiers.ts` shipped with a 5-tier system (TRIAL/FREE/PRO/TEAMS/ENTERPRISE). _Superseded 2026-07-05: PRO removed, now 4-tier TRIAL/FREE(Solo)/TEAMS/ENTERPRISE — see §1._ -- `feature-flags.ts` shipped. -- Persona data/logic split (`persona-data.ts` ↔ `personas.ts`). -- **All 4 new personas shipped** (general-purpose, planner, verifier, coordinator) — `persona-data.ts` verified. -- **AgentPersona interface extended** with disallowedTools / failurePatterns / isReadOnly / tagline / bestFor / wontDo — verified in `personas.ts`. -- **`behavioral-spec.ts` split** into named sections with `=== CRITICAL ===` markers; `COMPACTION_PROMPT` exported. -- **Orchestrator section caching** shipped in `buildSystemPrompt()`. -- **OnboardingWizard TEMPLATES expanded to 15**, all wired to `PERSONAS`. -- Stripe installed (`stripe@^21.0.1`) in root deps. -- Evolution subsystem fully present (10+ files, closed loop end-to-end). -- **PromptAssembler v5 PoC complete** — see `docs/plans/POLISH-SPRINT-2026-04-18.md`. -- **Premium harness reached HONEST 21/21** (May 2026 S1) — every pillar regression-locked + composing. Full agent suite 2657/2657. See `memory/project_session_handoff_0519_s1.md`. - -**AI-OS arc (May 2026 S1/S2, 14 commits on origin):** -- Phase 0 — Tool detection PoC (`packages/agent/src/tool-detection.ts`) for eight registered AI-tool surfaces, hermetic + cross-platform. Registration is broader than release support. -- Phase 1A — WaggleDance v2 dispatcher branches wired (discovery/routed_share/model_recipe/knowledge_match/task_claim/model_recommendation). -- Phase 1B — Local sidecar surface (`/api/waggle-dance/signal` + `/signals`), SignalBus ring buffer, personal-tier-eligible. -- Phase 1C — Bridge: v2 bus → existing `/api/waggle/signals` UI stream (zero frontend changes). -- Phase 1D — Shim-core signal emitter library (`@waggle/hive-mind-shim-core` `maybeEmitDiscovery`). -- Phase 1E — Codex Stop hook wired to `maybeEmitDiscovery` (opt-in via `WAGGLE_SIGNAL_EMIT`). -- Phase 2A — Launcher backend (`/api/tools/launch`, `/api/tools/hooks`). -- Phase 2B — LauncherApp dock surface (`apps/web/src/components/os/apps/LauncherApp.tsx`). -- Phase 3 — Skill diffusion (D1 fire → `skill_share` broadcast via `onSkillDistillationFire` callback). -- Phase 4 — Eight-tool inventory/detection surface + Mission Control tile + Memory provenance badge + launch-with-prompt textarea + process tracker / 'Running' badge. The in-scope agent-integration release cohort is Claude Code, Codex, and Hermes; Cursor and OpenClaw are roadmap-only. - -End-to-end: detect → install hooks (reversible) → launch with `WAGGLE_WORKSPACE_ID` env → hook captures → shim emitter → bus → bridge → UI. Rollback tag: `checkpoint/pre-ai-os-2026-05-20`. AI-OS exploration doc: `docs/plans/AI-OS-EXPLORATION-2026-05-19.md`. - -### Open Work -| # | File | What | -|---|---|---| -| 1 | Spawn Agent + Dock wiring | P36 already wired in `Dock.tsx`+`Desktop.tsx`; P35 third-tier fallback (LiteLLM → runtime model → provider catalogs) landed `14942be`. Residual: runtime verification on a clean install. | -| 2 | Light mode finish | P40/P41 + CR-2 — semantic-token migration is done (no hive-950 references except a comment); remaining issues are render-time fine-tuning (BootScreen visual polish + a few header-styling judgments) that need a binary build to validate. | -| 3 | External-tool release cohort | **Windows Solo scope fixed 2026-08-02.** Claude Code, Codex, and Hermes are the in-scope agent-integration cohort. Cursor and OpenClaw implementations remain in-tree as roadmap work and are fail-closed in production surfaces. Claude Desktop, Codex Desktop, and Hermes Desktop are convenience launch surfaces, not separate agent-acceptance targets. | - -**Closed during May 2026 backlog sweep:** -- ✅ OW-6 PersonaSwitcher two-tier — shipped via M-01 (`PersonaSwitcher.tsx` + `lib/persona-tier.ts` + `lib/persona-tooltip.ts`); 26/26 tests passing -- ✅ CR-7 AGENTS.md §10 update (this entry) -- ✅ P35 Spawn Agent "no models available" (`14942be`) -- ✅ QW-1..QW-5 quick wins (all already shipped per `grep` verification) -- ✅ CR-2 hive-950 → semantic tokens (only comment-level refs remain) -- ✅ M7 Stripe products — both test (`acct_1SzHlbC0mmjh4oEM`) and live (`CNCrMQy1f7`) accounts hold the full 2 products × 2 prices (monthly + annual) with `pro_monthly` / `pro_annual` / `teams_monthly` / `teams_annual` lookup keys. Verified via `stripe products list` + `stripe prices list`. Live price IDs documented in `docs/launch/drafts/2026-05-12-apps-www-deployment-readiness.md`. _Note (Solo-vs-Team collapse 2026-07-05): the PRO products/prices are **retained in Stripe for legacy-sub servicing only** — no new PRO checkout is offered. Only TEAMS is an active checkout price._ -- ✅ E-10 Stripe tier-enforcement wiring — webhook handler was already complete (signature + idempotency + 3 event handlers in `packages/server/src/stripe/webhook.ts`); session closed the residual gap by extending `tierFromPriceId()` in `packages/server/src/stripe/index.ts` to resolve the full 4-var contract (`STRIPE_PRICE_PRO_MONTHLY` / `_ANNUAL` / `STRIPE_PRICE_TEAMS_MONTHLY` / `_ANNUAL`) alongside legacy single-vars + `STRIPE_PRICE_BASIC`. 17/17 webhook tests green; annual subscriptions now resolve through the webhook. _Note (Solo-vs-Team collapse 2026-07-05): `tierFromPriceId()` still reads the legacy PRO/BASIC price envs, but now maps them → `'FREE'` (Solo) so a legacy PRO subscriber lands on Solo rather than a removed tier. Only TEAMS resolves to a paid tier._ -- ✅ M2 Codex export — `data-ffbb9f0b-…batch-0000.zip` (30 MB) on Desktop\MEMORIES\Codex\, dated 2026-04-17. Ready for E-11 ingestion. -- ✅ M3 Gemini export — `takeout-20260416T224803Z-3-001.zip` (437 MB) on Desktop\MEMORIES\Google\, dated 2026-04-17. Ready for E-11 ingestion. -- ⏭️ M1 ChatGPT export — skipped by Marko 2026-05-21 (export emails never arrived after multiple requests). -- ⏭️ M4 Perplexity export — skipped by Marko 2026-05-21 (research-burst usage; marginal corpus contribution). -- ✅ M6 judge roster — Opus 4.7 / GPT-5.4 / Gemini 2.5 Pro / Haiku 4.5 locked 2026-05-21. -- ✅ C-1 LoCoMo Memory SOTA — **CURRENT CANONICAL: 86.49% overall** (7-lane W4, Memori *same-judge* protocol — GPT-4.1-mini answerer+judge, N=1540), **+4.54pp over Memori 81.95** (z=4.64, p<10⁻⁵), leading/tying every category. Mem0 re-run on our ruler = **73.96** overall (**temporal +30.8pp** landslide; write-time dating vs Mem0 ingestion-time). **CORRECTED 2026-07-01: the prior 87.66% did NOT reproduce on a fresh judge pass (stale-verdict-replay inflation; archived-substrate 85.19% / current 86.49%). 86.49% is the fresh reproducible number** — pinned + offline-verifiable at [`benchmarks/results/locomo-sota-2026-06/`](benchmarks/results/locomo-sota-2026-06/) (`node recount.mjs` → 1332/1540); record in `docs/analysis/locomo-87.66-vs-85.26-integrity-2026-06-30.md`. Paper/arXiv in [`docs/paper/`](docs/paper/); OSS `marolinik/hive-mind` @ `bc4eba1`, PR #14. - - ~~_SUPERSEDED (v5 self-judge, N=320, 2026-05-11): 73.1% Opus 4.7 / 73.4% Qwen3.6, +4.6pp over Mem0 paper; trio-strict 67.8% AND-of-3. The 73.1/73.4 self-judge convergence + 67.8 trio-strict remain valid as the conservative v5-arc framing but are no longer the headline. See `D:/Projects/hive-mind-test/scripts/locomo/data/reports/RESULT-v5-2026-05-11.md`._~~ -- ✅ C-2 Substrate Claim — done 2026-04-25: Stage 3 v6 N=400, Fisher one-sided p = 8.07 × 10⁻¹⁸, +19.25pp retrieval-vs-no-context lift. "GEPA Full-System canary" expansion explicitly DROPPED 2026-04-30 per PM strategic reset. See `D:/Projects/waggle-os-gaia2-wt/benchmarks/results/stage3-n400-v6-final-analysis.md`. - -### Closed 2026-05-21 (E-14 + audit-trail surfacing) - -- ✅ **E-14 hive-mind v0.3.0 promotion** — shipped on `marolinik/hive-mind` in 3 commits + 1 annotated tag (`b5c1e8f` wiki-web port, `842f390` benchmarks/locomo, `507e0cf` release commit, tag `v0.3.0`). README + CHANGELOG refreshed, 9 versions at 0.3.0, npm install + tsc build clean, vitest 308/312 (4 pre-existing dispatch.test.ts failures documented as v0.3.x followup — same on baseline `20bce16` so not session-induced). Substrate-claim evidence (LoCoMo 73.1% + Fisher p=8.07e-18) now publicly visible. Unblocks S-1 (OSS launch timing) — "before Waggle" is the default since the substrate claim is now public. - -### New open work surfaced 2026-05-21 - -| # | Item | What | -|---|---|---| -| C-3 (reframed) | Full GAIA 2 Phase 4 benchmark | Phase 3 closed in HALT 2026-04-30 (commit `104aa5a` in `waggle-os-gaia2-wt`). Probe showed $4.09/invocation (9-31× over original estimate), narrow-proxy adapter approach economically non-viable. Phase 4 needs Docker + ARE proper agentic execution environment + new adapter strategy. Real engineering arc — scope + budget recalibrate pending Phase 4 design. | - -For the full polish+launch backlog see `docs/plans/BACKLOG-CONSOLIDATED-2026-04-17.md` (~145 items; ~50% are stale-but-done per the May 2026 verification sweep) and the AI-OS arc in `docs/plans/AI-OS-EXPLORATION-2026-05-19.md`. - ---- - -## 11. Glossary - -| Term | Definition | +| Term | Meaning | |---|---| -| Hive DS | Waggle design system — honey/hive-950/accent tokens in `waggle-theme.css` | -| FrameStore | SQLite-backed memory frame storage (`packages/hive-mind-core/src/mind/frames.ts`) | -| HybridSearch | Vector + keyword search (`packages/hive-mind-core/src/mind/search.ts`) | -| KnowledgeGraph | Entity-relation graph (`packages/hive-mind-core/src/mind/knowledge.ts`) | -| IdentityLayer | Personal identity persistence (`packages/hive-mind-core/src/mind/identity.ts`) | -| AwarenessLayer | Active task/state tracking (`packages/hive-mind-core/src/mind/awareness.ts`) | -| Cognify | Memory extraction pipeline (`packages/agent/src/cognify.ts`) | -| Harvest | Conversation/file ingestion (`packages/hive-mind-core/src/harvest/`) | -| Mind | Per-workspace persistence layer (`packages/hive-mind-core/src/mind/`) | +| Sidecar | The local Fastify server (`packages/server/src/local`) that the UI talks to | +| Memory contract | The interface Waggle uses to remember, search, get, update and delete memories (P0.3) | +| mem0 | Open-source memory library (`mem0ai`, Apache-2.0) behind the contract, run locally | +| Hive DS | Waggle design system tokens (`waggle-theme.css`) | | BEHAVIORAL_SPEC | Core agent rules (`packages/agent/src/behavioral-spec.ts`) | -| Sidecar | Node.js Fastify server bundled into Tauri (`/sidecar`) | -| KVARK | Egzakta sovereign enterprise AI — top of the Waggle funnel | -| LiteLLM | Optional server/team deployment proxy config (`litellm-config.yaml`); Windows Solo uses the bundled no-Python proxy and smart router | -| WaggleDance | Multi-agent coordination package (`packages/waggle-dance`) | -| Weaver | Memory consolidation and session-skill extraction engine (`packages/weaver`) | -| Evolution | Self-improvement subsystem (`evolution-*.ts`, `judge.ts`, `iterative-optimizer.ts`) | -| applyPersonaToolFilter / filterMcpToolsForPersona | Enforced local and MCP per-persona allowlist/denylist filtering (`packages/server/src/local/persona-tool-filter.ts`) | - ---- - -Maintained by Marko Markovic · Egzakta Group · April 2026 -waggle-os.ai · www.kvark.ai +| Weaver | Memory consolidation and session-skill extraction (`packages/weaver`) | +| WaggleDance | Multi-agent team coordination (`packages/waggle-dance`), postponed | +| Work package | A unit of the conversion plan: 0.x, P0.x, P1.x, P2.x | +| UF-NNN | An entry in the upstream fixes log (`docs/oss/upstream-fixes.md`) | diff --git a/CLAUDE.md b/CLAUDE.md index 7327235..140ed2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,729 +1,31 @@ -# CLAUDE.md — Waggle OS -### Claude operational companion +# CLAUDE.md — Waggle Community Edition -> Read `AGENTS.md` in full before touching code. `AGENTS.md` is the canonical operating -> contract for all agents and wins on conflict. This file is a Claude-oriented companion; -> keep shared guidance aligned, but never treat it as a second source of truth. +> Read [`AGENTS.md`](AGENTS.md) in full before touching code. It is the canonical operating +> contract for this branch and wins on conflict. This file only adds Claude-specific notes. ---- +## Before you start -## 0. How to Use This File +- Check the decision records in [`docs/oss/adr/`](docs/oss/adr/README.md) for anything your + task touches: memory, monetization, team mode, self-learning, WhatsApp, analytics. +- Find the work package your task belongs to (0.x, P0.x, P1.x, P2.x) and stay inside it. +- Compare your verification results with [`docs/oss/baseline.md`](docs/oss/baseline.md). -This file has two parts: **what the project is** (Sections 1-2) and **how to work on it** (Sections 3-9). -If you're about to write code, **Section 3** is the most important thing you'll read. +## Local servers ---- +- A sidecar on `:3333` may already be running and serving the root `dist/`. Check with + `lsof -i :3333 -sTCP:LISTEN` before starting one. Do not start a second instance. +- `npm run build`, `npm run build:all` and the Playwright e2e web server rewrite the root + `dist/`; a running sidecar then returns 404 for the new assets until it restarts. Ask before doing either if you + did not start that sidecar. -## 1. What Waggle OS Actually Is +## Working with subagents -**Waggle OS** is a workspace-native AI agent platform with persistent memory. Its current desktop -release scope is Windows-first: a Tauri 2.0 app with a Vite-bundled web UI and bundled Node.js -sidecar. macOS packaging, signing, notarization, and runtime certification are roadmap work. +- Mechanical removals across many files (tiers, KVARK, Stripe) suit background agents. + Review their diffs before committing and run the verification commands from `AGENTS.md`. +- Use read-only agents for broad searches; keep their conclusions, not the file dumps. -**Strategic function:** Waggle is the demand-creation and qualification engine for KVARK — -Egzakta Group's sovereign enterprise AI platform. +## Writing -### Tiers (verified from `packages/shared/src/tiers.ts` — 4-tier: TRIAL/FREE(Solo)/TEAMS/ENTERPRISE, Solo-vs-Team collapse 2026-07-05) - -| Tier | Price | Purpose | -|---|---|---| -| TRIAL | $0 / 15 days | TEAM preview — 15 days of Team, then Solo | -| FREE (Solo) | $0 forever | Everything personal: unlimited workspaces+connectors, marketplace/custom skills, cloud embeddings, PDF/JSON export, basic audit — free forever | -| TEAMS | $49/mo per seat | Shared workspaces, WaggleDance, governance | -| ENTERPRISE | Consultative | KVARK sovereign on-prem (www.kvark.ai) | - -> PRO ($19/mo) was removed in the Solo-vs-Team collapse (2026-07-05); its -> capabilities folded into FREE (Solo). `TIER_LABELS` displays FREE as "Solo". - -**Moat strategy:** Memory + Harvest is free forever (lock-in moat). Agents, skills, -and connectors are all free (they generate memory). Team collaboration (shared memory, -WaggleDance, governance) is the upgrade trigger. - -### Current Release Qualification Contract (2026-08-22) - -- Launch gate: **Windows Solo only**. -- In-scope external-agent release cohort: **Claude Code, Codex, and Hermes**. Each integration - uses the user's own installed client and its official user authentication. -- **Cursor and OpenClaw are roadmap-only**: detection metadata may remain, but production launch, - hooks, Fleet/task dispatch, and direct run routes must fail closed for them. -- Claude Desktop, Codex Desktop, and Hermes Desktop may remain as detected convenience launch - surfaces; they are not separate memory-hook or agent-acceptance targets in this release gate. -- ChatGPT/OpenAI is a model/provider and memory-import surface, not a separate launcher target. -- The Windows Solo launch contract requires an exact-revision Windows installer qualification receipt to - prove its bundled Node sidecar, no-Python OpenAI-compatible proxy, Waggle-managed local runtime/model, default - in-process embedding path, and freedom from developer Node, Docker, Python, external LiteLLM, or a - separately installed Ollama. A separate revision-bound router receipt must prove the smart-router primary, - compact-tool-context, budget, and fallback paths. A user-installed Ollama remains optional. -- Every receipt is valid first for the exact source revision and artifact SHA-256 it names. An older - router, persona, or authentication receipt is historical unless the current launch recommendation - explicitly carries it forward through a bounded no-impact attestation. -- Bounded carry-forward is allowed only when an exhaustive intervening-diff review proves that no - covered runtime surface changed, independent review approves that classification, and focused tests - and lint cover the intervening changes. Any affected persona, chat, provider, authentication, memory, - routing, or tool-context behavior requires a fresh receipt. Installer, public signing, and sealed - security artifacts remain revision-bound and must name the exact candidate they cover. -- A release-record-only Markdown descendant does not change the frozen runtime revision or installer - SHA-256. The eventual public hosted artifact and managed Deep Scan must instead be regenerated for - and name the exact approved release-tag commit. -- Persona evidence requires a complete 30-result collection across 10 personas at >=95/100 after - any explicitly documented independent semantic adjudication, plus either a fresh release-revision - run or an approved bounded no-impact attestation. Never relabel a non-gating collection as a - canonical deterministic seal. Claude Code/Codex/Hermes official user-auth canaries follow the - same carry-forward rule. GO also requires zero unresolved Critical/High findings. -- Do not claim release approval, production readiness, an overall 9.5/10, or competitor superiority - unless the current launch recommendation says GO for that same release. - -### Evidence authority - -Exact candidate revisions, installer and receipt hashes, carry-forward boundaries, open -checks, and the current verdict live only in -`docs/production-readiness/09-LAUNCH_RECOMMENDATION.md`. Do not duplicate an old -candidate table here or infer that an ancestor's installer certifies a later HEAD. The -repository remains private until an explicit open-source and licensing decision is made. -Public GO remains blocked until a publicly trusted Authenticode artifact and an exact-candidate -sealed managed Deep Security report close with no unresolved Critical/High findings. - -### Key Technology Facts (Verified August 2026) - -| Layer | Stack | -|---|---| -| Frontend | React **19** + TypeScript + Vite + Tailwind 4 + base-ui/react | -| Desktop | Tauri 2.0 (Rust shell) | -| Backend | Fastify sidecar (Node.js, bundled into Tauri) | -| LLM routing | Windows Solo release contract: bundled no-Python OpenAI-compatible proxy and smart router; optional LiteLLM deployment config | -| Database | SQLite via @waggle/core (better-sqlite3 + sqlite-vec-windows-x64) | -| Memory | FrameStore + HybridSearch + KnowledgeGraph + IdentityLayer + AwarenessLayer | -| Agent runtime | `packages/agent/src/agent-loop.ts` | -| Billing | Stripe (installed; `stripe@^21.0.1`) | -| Design | Hive DS — honey #e5a000 / hive-950 #08090c / accent #a78bfa | -| Tests | Vitest (unit) + Playwright (E2E) | -| Deploy | Windows Tauri installer release contract; optional Dockerfile + docker-compose.production.yml + render.yaml for server/team deployment | - -Package manager: npm with the root `package-lock.json`. Source development requires Node -`^20.19.0 || >=22.12.0`; the packaged Windows desktop runtime is pinned to Node `22.23.2`. - ---- - -## 2. Repository Structure (Verified) - -### Top level -``` -waggle-os/ -├── app/ # Tauri desktop shell (minimal React surface) -├── apps/ -│ ├── web/ # <-- MAIN web app UI (this is where most components live) -│ └── www/ # Landing page (waggle-os.ai) -├── packages/ # 28 workspace packages (see below) -├── sidecar/ # Node.js sidecar bundled into Tauri -├── scripts/ # build-sidecar, bundle-native-deps, bundle-node -├── tests/ # Cross-cutting integration tests -├── docs/ # ARCHITECTURE.md and others -├── cowork/ # Scratchpad / planning / handoff docs (historical; CLAUDE.md promoted to root) -├── .planning/ .scratch/ .mind/ # Working notes -├── docker-compose.yml + .production.yml + Dockerfile + render.yaml -├── litellm-config.yaml # LLM router config -├── playwright.config.ts + playwright-e2e.config.ts -├── vitest.config.ts + vitest.setup.ts -└── package.json (workspaces: apps/*, packages/*) -``` - -### Packages (`packages/`, 28 workspaces — verified 2026-08-02) -``` -Core (15): -admin-web cli launcher marketplace -agent core memory-mcp optimizer -sdk server shared waggle-dance -weaver wiki-compiler worker - -hive-mind OSS source set (13 — curated forward-port target is marolinik/hive-mind; see §7.5): -hive-mind-core hive-mind-cli hive-mind-shim-core hive-mind-mcp-server -hive-mind-wiki-compiler hive-mind-hooks-core -hive-mind-hooks-{claude-code, claude-desktop, codex, codex-desktop, - cursor, hermes, openclaw} -``` -> Note: the prior list said "16" and included `ui`, which has no `package.json` -> (not a workspace). The live count is 28: 15 product packages and 13 -> `hive-mind-*` packages. - -### `packages/agent/src/` — MOST ACTIVE (94 .ts files + 4 subdirs) - -Key files (not exhaustive — grep before creating anything new): -``` -agent-loop.ts Core execution loop -orchestrator.ts buildSystemPrompt(), recallMemory() -personas.ts AgentPersona interface + logic (data split out) -persona-data.ts Pure PERSONAS declarative data array -custom-personas.ts loadCustomPersonas() from disk -behavioral-spec.ts BEHAVIORAL_SPEC rules -tool-filter.ts filterToolsForContext() -injection-scanner.ts scanForInjection() — 3 pattern sets -cost-tracker.ts CostTracker + model pricing -skill-frontmatter.ts parseSkillFrontmatter() -kvark-tools.ts kvark_search, kvark_ask_document (tier-gated) -feature-flags.ts EXISTS — don't recreate -subagent-orchestrator.ts Subagent spawn/coord -workflow-composer.ts -workflow-harness.ts -workflow-templates.ts - -Evolution subsystem: - evolution-orchestrator.ts evolution-deploy.ts evolution-gates.ts - evolution-llm-wiring.ts evolve-schema.ts iterative-optimizer.ts - judge.ts eval-dataset.ts compose-evolution.ts - -Capability & trust: - capability-acquisition.ts capability-router.ts trust-model.ts - permissions.ts credential-pool.ts confirmation.ts - -Quality & correction: - quality-controller.ts contradiction-detector.ts - correction-detector.ts improvement-detector.ts improvement-wiring.ts - loop-guard.ts iteration-budget.ts - -Subdirs: - commands/ connectors/ mcp/ providers/ -``` - -### `packages/core/src/` -``` -Top-level: config.ts, cron-store.ts, file-store.ts, install-audit.ts, - logger.ts (createCoreLogger), memory-import.ts, migration.ts, - multi-mind.ts, multi-mind-cache.ts, optimization-log.ts, - skill-hashes.ts, team-sync.ts, telemetry.ts, vault.ts, - workspace-config.ts, index.ts - -Subdirs: - compliance/ — compliance reporting, interaction-store, status-checker - -MOVED (2026-04-30 monorepo migration): the memory substrate `mind/` (db/schema/ - identity/awareness/frames/sessions/search/knowledge/scoring/reconcile/ontology/ - concept-tracker/entity-normalizer/evolution-runs/execution-traces/ - improvement-signals/embedding-provider/*-embedder) and `harvest/` (chatgpt/claude/ - claude-code/gemini/perplexity/pdf/plaintext/markdown/url/universal adapters + - pipeline.ts + dedup.ts) now live at **packages/hive-mind-core/src/{mind,harvest}/**, - NOT under packages/core/. The OSS mirror is curated from there through a maintainer-reviewed - forward-port (§7.5); raw subtree branches are never publish sources. -``` - -For the deep-dive on what the mind/ substrate does, see [`docs/memory-architecture.md`](docs/memory-architecture.md). - -### `packages/shared/src/` -``` -types.ts User, Team, AgentDef, Task, WaggleMessage -constants.ts Team roles, job statuses -schemas.ts Zod schemas -tiers.ts TIERS + TierCapabilities (canonical 4-tier: TRIAL/FREE(Solo)/TEAMS/ENTERPRISE) + TIER_LABELS/tierLabel -mcp-catalog.ts MCP server catalog -index.ts Barrel -``` - -### `app/` (Tauri desktop shell) -``` -app/src-tauri/ # Rust shell + capabilities/ + tauri.conf.json -app/scripts/ # build/installer/signing TS tooling (tauri-tsc gate target) -``` - -**Note:** `app/` is now the Tauri Rust shell only — there is no `app/src/`. The -React cockpit UI moved to `apps/web` long ago; the desktop binary loads the -`apps/web` dist. All React UI lives in `apps/web/src/`. - -### `apps/web/src/` (MAIN UI) -``` -apps/web/src/ -├── assets/ components/ hooks/ lib/ -├── pages/ providers/ test/ - -components/ -├── os/ -│ ├── apps/ # Per-app UI shells -│ └── overlays/ # OnboardingWizard.tsx, PersonaSwitcher.tsx live HERE -└── ui/ # Shared UI primitives -``` - -### Build Commands (verified from `package.json`) -```bash -npm run dev # Vite dev server (apps/web) -npm run build # Vite build to /dist (apps/web) -npm run build:packages # tsc --build: shared -> core -> agent -> server (order matters) -npm run build:all # Packages then web -npm run lint # ESLint repo-wide -npm run test # Vitest unit tests -npm run test:e2e # Playwright API tests -npm run test:visual # Playwright visual regression -npm run test:all # Full Playwright -``` - -### Verification Commands (run these, don't claim "it compiles") -```bash -npx tsc --noEmit --project packages/agent/tsconfig.json -npx tsc --noEmit --project packages/server/tsconfig.json # sidecar — runs via tsx (transpile-only), so NOT typechecked by `npm run build` -npx tsc --noEmit --project app/tsconfig.json -npm run test -- --run -npm run lint -``` -> `npm run build` typechecks **only `apps/web`**. The Fastify sidecar runs via -> `tsx` (transpile-only) — server-route type errors ship undetected unless you -> run the `packages/server` tsc above. (A real type error slipped through this -> way on 2026-05-28; see `docs/addictiveness-audit-2026-05-28/REDUNDANCY-AUDIT.md`.) - -### Windows Solo release commands (PowerShell 7; final frozen clean checkout) - -```powershell -# Local build-host preparation (the installed desktop has none of these prerequisites). -npm ci -npm ci --prefix app --ignore-scripts -npm run build:packages - -# Local unsigned build only; this verifies packaging/runtime, not public trust. -npm --prefix app run tauri:build:win - -# Optional internal-pilot build. Its private test root is not public trust. -npm --prefix app run tauri:build:win:pilot-signed - -# Internal clean-profile certification. Omit public-signature requirements for a pilot. -pwsh -NoProfile -File scripts/certify-windows-installer.ps1 ` - -InstallerPath "" ` - -ExpectedSourceRevision "<40-character-final-HEAD>" ` - -VerifyManagedModel -``` - -Production signing is hosted-only. Do not run `new-windows-signing-handoff.ps1`, -`sign-windows-artifact.ps1`, or a local thumbprint-signing substitute to create a -release artifact. `.github/workflows/release.yml` is authoritative and must run from -an approved exact release tag. Its Windows chain is `build-windows-prebuilt` -> -`prepare-windows-signing` -> `sign-windows` -> `certify-windows` -> -`attest-windows` -> `publish-windows`. -`sign-windows` requires Azure Artifact Signing OIDC variables, a federated credential -scoped to the exact approved tag ref, and the least-privilege certificate-profile signer -role. Before Azure authentication, it must bind the push event, repository, tag, -workflow ref/SHA, clean checkout, and fresh `origin/main` ancestry. Signing may produce -private Actions artifacts, but public attestation and `publish-windows` remain disabled -while the repository is private; publication additionally requires -`WINDOWS_PUBLIC_RELEASE_AUTHORIZED` to be explicitly `true`. The existing `production` -environment isolates public-attestation OIDC claims from the exact-tag Azure signer. -Private repositories require GitHub Enterprise Cloud for GitHub artifact attestations, -so the sealed certified artifact is the terminal private-repository output. The approved -signer subject and timestamp must still pass before credential-free certification. -Never treat the local certification command as signed or change repository visibility -without an explicit OSS/licensing decision. -The certified installed desktop must not depend on developer Node.js, Python, -Docker, external LiteLLM, or a separately installed Ollama. - ---- - -## 3. Behavioral Rules — How You Must Work - -These rules apply to every code change. They exist because violations have cost real debugging time. - -### 3.1 Think Before Coding - -**Don't assume. Don't hide confusion. Surface tradeoffs.** - -Before implementing anything: -- State your assumptions explicitly. If uncertain, ask. -- If multiple interpretations exist, present them — don't pick silently. -- If a simpler approach exists, say so. Push back when warranted. -- If something is unclear, stop. Name what's confusing. Ask. - -=== CRITICAL === -The single most expensive LLM failure mode is making wrong assumptions and building -100+ lines on top of them. The fix costs 10x what the question would have cost. -Stop. Ask. Then build. -=== END CRITICAL === - -### 3.2 Simplicity First - -**Minimum code that solves the problem. Nothing speculative.** - -- No features beyond what was asked. -- No abstractions for single-use code. -- No "flexibility" or "configurability" that wasn't requested. -- No error handling for impossible scenarios. -- If you write 200 lines and it could be 50, rewrite it. - -Test: **"Would a senior engineer say this is overcomplicated?"** If yes, simplify. - -### 3.3 Surgical Changes - -**Touch only what you must. Clean up only your own mess.** - -When editing existing code: -- Don't "improve" adjacent code, comments, or formatting. -- Don't refactor things that aren't broken. -- Match existing style, even if you'd do it differently. -- If you notice unrelated dead code, **mention it** — don't delete it. - -When your changes create orphans: -- Remove imports/variables/functions YOUR changes made unused. -- Don't remove pre-existing dead code unless asked. - -Test: **Every changed line should trace directly to the request.** - -### 3.4 Goal-Driven Execution - -**Define success criteria. Loop until verified.** - -Transform vague tasks into verifiable goals: -- "Add validation" → "Write tests for invalid inputs, then make them pass" -- "Fix the bug" → "Write a test that reproduces it, then make it pass" -- "Refactor X" → "Ensure tests pass before and after" - -For multi-step tasks, state a brief plan: -``` -1. [Step] -> verify: [check] -2. [Step] -> verify: [check] -3. [Step] -> verify: [check] -``` - -A task is not done until verification passes. "I think this works" is not verification. - -### 3.5 Context Discipline - -- **Context decay:** After 10+ messages, re-read any file before editing. Do not trust memory. -- **File read budget:** Files >500 LOC require chunked reads. Never assume complete view. -- **Truncation:** Tool results >50k chars are silently truncated. If sparse, re-run narrower. -- **Re-read before edit. Re-read after edit.** Max 3 edits per file before verification read. -- **Exhaustive grep on rename:** Direct refs, type-level, string literals, dynamic imports, - re-exports/barrel entries, test files. **One grep is never enough.** - -### 3.6 Check Before Create - -Before adding a new file, **grep first.** The repo has ~94 files in `packages/agent/src` -alone. If you're about to write something that might already exist, it probably does. -See Section 8 for known utilities. - -### 3.7 Output Discipline - -- **Chat reply budget.** Long specs, handoffs, audit reports, and multi-phase plans MUST - be written to files (memory/, docs/, or via `/handoff`), not rendered inline. The chat - is a pointer; the file is the deliverable. -- **Chunk long work.** Multi-phase roadmaps and >1k-line specs: implement in phases, - commit per phase, give a 3-line status, then stop and await the next instruction. Do - not stream an exhaustive summary that blows the output budget. -- **Rationale:** 13+ prior sessions were lost mid-response to the 500-output-token cap. - Surface shortly, persist richly. - -### 3.8 Handoff Discipline - -- **Use the skill.** End-of-session handoffs invoke `~/.claude/skills/handoff/`, which - enforces verification (`git status`, tests N/M, `npx tsc --noEmit` on touched packages) - BEFORE writing the doc. Do not hand-write handoffs that skip the gate. -- **Canonical location.** Handoffs live at - `C:/Users/MarkoMarkovic/.claude/projects/D--Projects-waggle-os/memory/project_session_handoff__s.md`, - with the memory-dir MEMORY.md "START HERE" pointer updated. That is the single source - of truth for what shipped / what's left / how to roll back. -- **Never hide failures.** Failing tests, unverified MCP reconnects, wrong build dir — - surface under "What's still open" in the handoff. Clean-looking handoffs that hide rot - cost the next session hours. - ---- - -## 4. Pre-Work Protocol - -Before any structural refactor on a file >300 LOC: -1. Remove dead props, unused exports, unused imports, `console.log`. -2. Commit separately: `chore(scope): dead code removal — [filename]` - -**Phased execution:** Max 5 files per phase. Complete → verify → await approval → next phase. - -**Senior dev override:** If architecture is flawed, state is duplicated, or patterns -are inconsistent — state it and propose a fix. Standard: *"What would a senior engineer -reject in review?"* - ---- - -## 5. Persona Architecture - -### Shipped (22 personas — data in `persona-data.ts`, logic in `personas.ts`) -The original 13 + 4 universal/orchestration + 5 domain personas all shipped. -The PersonaSwitcher groups them into **two tiers** (`apps/web/src/lib/persona-tier.ts`): - -**Universal Modes (8 — always available in every workspace):** -general-purpose, planner, verifier, coordinator, researcher, writer, analyst, coder -- **general-purpose** — versatile default, full tool access -- **planner** — read-only strategic planning, no file writes (`isReadOnly`) -- **verifier** — adversarial QA, read-only, VERDICT output format (`isReadOnly`) -- **coordinator** — pure orchestrator, spawn/list/get_agent_result only (gated by `FEATURE_FLAGS.COORDINATOR_MODE`) - -**Specialists (14 — template-scoped via `TEMPLATE_SPECIALISTS`):** -project-manager, executive-assistant, sales-rep, marketer, product-manager-senior, -hr-manager, legal-professional, finance-owner, consultant, support-agent, -ops-manager, data-engineer, recruiter, creative-director - -> Note: the onboarding picker (`onboarding/constants.ts` → `ALL_ONBOARDING_PERSONAS`) -> intentionally surfaces only **19** of the 22 — it omits planner/verifier/coordinator -> (read-only/orchestration modes don't make sense as a workspace's *starting* brain) and -> uses its own 3-way grouping (universal/knowledge/domain). Same canonical personas, a -> different view for a different UI moment. `persona-data.ts` is the single source of truth. - -**Split is done:** `persona-data.ts` holds the pure `PERSONAS` array; -`personas.ts` exports the `AgentPersona` interface and logic only. - -### AgentPersona Interface — Shipped Fields (verified `personas.ts`) -```typescript -interface AgentPersona { - // core - id, name, description, icon, systemPrompt, modelPreference, - tools: string[], workspaceAffinity: string[], - suggestedCommands: string[], defaultWorkflow: string | null, - // guardrails + picker metadata (all optional, all shipped) - disallowedTools?: string[] // denylist — overrides tools[] on conflict - failurePatterns?: string[] // documented failure modes — shown in hover tooltip - isReadOnly?: boolean // true = no write tools after applyPersonaToolFilter/filterMcpToolsForPersona - tagline?: string // one sentence for picker hover - bestFor?: string[] // 3 example tasks in user-facing language - wontDo?: string // hard boundary statement - suggestedSkills?: string[] // installable from marketplace - suggestedConnectors?: string[] // connector IDs - suggestedMcpServers?: string[] // MCP server names from mcp-registry -} -``` - ---- - -## 6. Onboarding & PersonaSwitcher (correct paths) - -### OnboardingWizard -**Path:** `apps/web/src/components/os/overlays/OnboardingWizard.tsx` -(NOT `app/src/components/onboarding/` — that path doesn't exist.) - -Shipped: 6-step flow (`first-launch → who-are-you → model-gate → memory-import → -template → first-task`). The 15 TEMPLATES + the `TEMPLATE_PERSONA` mapping (template → -one default persona id) live in `overlays/onboarding/constants.ts`, wired to the -canonical persona ids from `persona-data.ts`. The wizard surfaces a **curated 6** of the -15 (`CURATED_ONBOARDING_TEMPLATES`) for the ≤2-min flow; the full 15 are reachable from -the workspace gallery later. (Picker persona roster = `ALL_ONBOARDING_PERSONAS`, the -19-of-22 view noted in §5.) - -### PersonaSwitcher -**Path:** `apps/web/src/components/os/overlays/PersonaSwitcher.tsx` - -Shipped (M-01): Two-tier layout — "UNIVERSAL MODES" (8, from `UNIVERSAL_MODE_IDS`) + -"YOUR WORKSPACE SPECIALISTS" (template-scoped via `getSpecialistsForTemplate` in -`lib/persona-tier.ts`). Hover tooltip (`buildPersonaTooltip`, `lib/persona-tooltip.ts`) -shows tagline + bestFor + wontDo. "Create Custom Persona" inline form POSTs to -`/api/personas`. - ---- - -## 7. Security Constraints (Non-Negotiable) - -1. **Vault-only secrets.** API keys belong in Vault or an untracked local `.env`, never in Git. `.env.example` may contain non-secret development defaults, but never usable credentials or secrets. -2. **Injection defense.** `scanForInjection()` from `injection-scanner.ts` MUST be called on all connector/external input. -3. **No eval, no dynamic require.** Tauri WebView is restricted. -4. **Tauri IPC allowlist.** Explicit in `app/src-tauri/capabilities/`. Never `allowlist: all: true`. -5. **Parameterized queries.** No string interpolation in SQL. Ever. better-sqlite3 supports parameters. -6. **KVARK contact data.** Submits to your API only — no third-party form services. -7. **Secrets in `packages/core/src/vault.ts`** — use it; don't build parallel secret stores. - ---- - -## 7.5. Memory Substrate Sync (waggle-os → hive-mind, curated forward-port) - -The memory substrate lives at **`packages/hive-mind-core/src/{mind,harvest}/`** (moved from -`packages/core/src/` in the 2026-04-30 monorepo migration). The public OSS mirror at -[`marolinik/hive-mind`](https://github.com/marolinik/hive-mind) is **generated FROM** this monorepo -via a **maintainer-curated forward-port** (NOT a mechanical `git subtree split` — see the -correction below). The mirror uses its own curated layout (`packages/core`, co-located tests, -rewritten imports) and **excludes** Waggle-proprietary content (see the exclusion list below). - -=== CRITICAL — sync policy (founder-ratified 2026-06-11) === -**The monorepo is the SOLE source of truth for the substrate. Never author substrate features -directly on the OSS mirror.** Parity is NOT automatic — it broke once: the cross-encoder reranker -(`inprocess-reranker.ts` + HybridSearch options) was written directly on `marolinik/hive-mind` -during the LoCoMo benchmark arc and existed ONLY there, discovered by the W4 recon and -reverse-ported in W4.2 (`f47ee8f`). Rules: -1. Substrate changes land in `packages/hive-mind-core/` here FIRST; the mirror is updated - through a reviewed, maintainer-curated forward-port afterward. -2. Benchmark/experiment work in a `D:/Projects/hive-mind` checkout is throwaway unless - reverse-ported here — port it the same arc, don't let it sit. -3. Run **`node scripts/oss-drift-check.mjs D:/Projects/hive-mind`** before every OSS release - push and after any arc that touched a hive-mind checkout. The checker compares the live - mapped trees with an immutable reviewed baseline: parity and reviewed adaptations are - allowed, while known blockers, unreviewed differences, or forbidden exports keep exit 1. -4. External PRs on the OSS repo are fine — the maintainer intentionally ports accepted changes - back here first, then prepares the next curated forward-port. -=== END CRITICAL === - -=== CORRECTION — how the sync ACTUALLY works (2026-06-12 drift analysis) === -The prior text here claimed the mirror is produced by `scripts/oss-subtree-split.sh` and that a -"subtree-split filter" handles the must-not-export files. **Both were false** (verified -2026-06-12, `docs/ux-refactor/oss-sync-finding-2026-06-12.md`): -- `scripts/oss-subtree-split.sh` produces RAW per-package branches with the WRONG layout - (`packages/hive-mind-core`, not the mirror's `packages/core`) and **no file filter ever - existed**. A raw split + push would have **leaked proprietary IP**. The script now carries a - hard ABORT guard (refuses to emit a branch containing the proprietary files) + a deprecation - header; it is for inspection / as a curation starting point ONLY, never a direct push source. -- **The real sync is a hand-curated forward-port** onto a maintainer feature branch in the OSS - clone (e.g. `feature/mono-parity-YYYY-MM-DD`): adapt the layout, rewrite imports, and STRIP the - excluded content. That curation — not a filter — is what keeps proprietary content out. - -**OSS-EXCLUDED (must NOT reach the public mirror):** -- Files: `vault.ts`, `evolution-runs.ts`, `execution-traces.ts`, `improvement-signals.ts`, - `compliance/**` (vault/compliance live in `@waggle/core`; the other three are barrel-exported - from `hive-mind-core` but stripped on export). Enforced by the script's abort guard. -- **Interleaved:** the `install_audit` table DDL + its rebuild migration inside - `mind/{schema.ts,db.ts}` are ALSO excluded (capability-install trust trail / EU-AI-Act - compliance — Waggle governance, not generic substrate). A file filter cannot catch this; only - the curated edit strips it. **Consequence:** substrate changes confined to `install_audit` - (e.g. P5/D4 `'uninstalled'`, #15 `trust_source` CHECK) have **nowhere to land on the mirror — - do NOT treat them as a pending OSS port.** -=== END CORRECTION === - -**To work on the substrate or publish the OSS mirror:** see -[`packages/hive-mind-core/CONTRIBUTING.md`](./packages/hive-mind-core/CONTRIBUTING.md), -[`scripts/oss-subtree-split.sh`](./scripts/oss-subtree-split.sh) (inspection/guard only), and -[`scripts/oss-drift-check.mjs`](./scripts/oss-drift-check.mjs) (run before every release; its -immutable baseline distinguishes parity, reviewed adaptations, known blockers, unreviewed -differences, and forbidden exports; every blocker or unreviewed entry must be resolved or -explicitly re-baselined through maintainer review before an OSS release). - -**Deprecated (do not rely on; do not delete):** the old dual-repo bidirectional-sync workflows -`.github/workflows/{mind-parity-check,sync-mind}.yml` and the `.github/sync.md` manual are **preserved -as deprecation anchors** from when the substrate was duplicated across two repos. Their trigger paths -(`packages/core/src/{mind,harvest}/**`) no longer exist, so they never fire; each carries a DEPRECATED -header explaining the migration. Leave them in place for audit trail. - ---- - -## 8. Already Built — Do Not Recreate - -Grep before creating. These exist and are functional: - -| File | What it does | -|---|---| -| `packages/agent/src/injection-scanner.ts` | `scanForInjection()` — 3 pattern sets | -| `packages/agent/src/cost-tracker.ts` | `CostTracker` + model pricing table | -| `packages/agent/src/tool-filter.ts` | `filterToolsForContext()` — allowlist/denylist | -| `packages/agent/src/skill-frontmatter.ts` | `parseSkillFrontmatter()`, `ParsedSkill` | -| `packages/agent/src/kvark-tools.ts` | `kvark_search`, `kvark_ask_document` (tier-gated) | -| `packages/agent/src/feature-flags.ts` | **EXISTS** — don't create | -| `packages/agent/src/persona-data.ts` | Canonical `PERSONAS` array (pure data) | -| `packages/agent/src/custom-personas.ts` | `loadCustomPersonas()` from disk | -| `packages/agent/src/judge.ts` | Evolution judging | -| `packages/agent/src/iterative-optimizer.ts` | Self-improvement loop | -| `packages/agent/src/capability-router.ts` | Per-capability routing | -| `packages/agent/src/loop-guard.ts` | Infinite loop prevention | -| `packages/agent/src/contradiction-detector.ts` | Memory conflict detection | -| `packages/shared/src/tiers.ts` | `TIERS`, `TierCapabilities` — canonical tier system | -| `packages/shared/src/mcp-catalog.ts` | MCP server catalog | -| `packages/core/src/vault.ts` | Secret storage | -| `packages/core/src/telemetry.ts` | Telemetry pipeline | -| `packages/hive-mind-core/src/harvest/pipeline.ts` | Harvest adapters + dedup | -| `packages/core/src/compliance/` | Compliance + audit | -| `apps/web/src/components/os/` | Main desktop cockpit UI loaded by Tauri | - ---- - -## 9. KVARK Integration - -**Canonical copy:** -> "Everything Waggle does — on your infrastructure, connected to all your internal systems. -> Full data pipeline injection, your permissions, complete audit trail, governance. -> Your data never leaves your perimeter." - -**URLs (hardcoded only in `kvark-tools.ts` and `KvarkNudge` component):** -- Product site: https://www.kvark.ai -- License server: https://license.waggle-os.ai/validate -- SaaS cloud: https://cloud.waggle-os.ai - -`kvark-tools.ts` gates `kvark_search` and `kvark_ask_document` to TEAMS/ENTERPRISE tiers. -Do not recreate or expose outside gating. - ---- - -## 10. Sprint Status (May 2026) - -### What Landed -**April 2026 baseline:** -- `tiers.ts` shipped with a 5-tier system (TRIAL/FREE/PRO/TEAMS/ENTERPRISE). _Superseded 2026-07-05: PRO removed, now 4-tier TRIAL/FREE(Solo)/TEAMS/ENTERPRISE — see §1._ -- `feature-flags.ts` shipped. -- Persona data/logic split (`persona-data.ts` ↔ `personas.ts`). -- **All 4 new personas shipped** (general-purpose, planner, verifier, coordinator) — `persona-data.ts` verified. -- **AgentPersona interface extended** with disallowedTools / failurePatterns / isReadOnly / tagline / bestFor / wontDo — verified in `personas.ts`. -- **`behavioral-spec.ts` split** into named sections with `=== CRITICAL ===` markers; `COMPACTION_PROMPT` exported. -- **Orchestrator section caching** shipped in `buildSystemPrompt()`. -- **OnboardingWizard TEMPLATES expanded to 15**, all wired to `PERSONAS`. -- Stripe installed (`stripe@^21.0.1`) in root deps. -- Evolution subsystem fully present (10+ files, closed loop end-to-end). -- **PromptAssembler v5 PoC complete** — see `docs/plans/POLISH-SPRINT-2026-04-18.md`. -- **Premium harness reached HONEST 21/21** (May 2026 S1) — every pillar regression-locked + composing. Full agent suite 2657/2657. See `memory/project_session_handoff_0519_s1.md`. - -**AI-OS arc (May 2026 S1/S2, 14 commits on origin):** -- Phase 0 — Tool detection PoC (`packages/agent/src/tool-detection.ts`) for eight registered AI-tool surfaces, hermetic + cross-platform. Registration is broader than release support. -- Phase 1A — WaggleDance v2 dispatcher branches wired (discovery/routed_share/model_recipe/knowledge_match/task_claim/model_recommendation). -- Phase 1B — Local sidecar surface (`/api/waggle-dance/signal` + `/signals`), SignalBus ring buffer, personal-tier-eligible. -- Phase 1C — Bridge: v2 bus → existing `/api/waggle/signals` UI stream (zero frontend changes). -- Phase 1D — Shim-core signal emitter library (`@waggle/hive-mind-shim-core` `maybeEmitDiscovery`). -- Phase 1E — claude-code Stop hook wired to `maybeEmitDiscovery` (opt-in via `WAGGLE_SIGNAL_EMIT`). -- Phase 2A — Launcher backend (`/api/tools/launch`, `/api/tools/hooks`). -- Phase 2B — LauncherApp dock surface (`apps/web/src/components/os/apps/LauncherApp.tsx`). -- Phase 3 — Skill diffusion (D1 fire → `skill_share` broadcast via `onSkillDistillationFire` callback). -- Phase 4 — Eight-tool inventory/detection surface + Mission Control tile + Memory provenance badge + launch-with-prompt textarea + process tracker / 'Running' badge. The in-scope agent-integration release cohort is Claude Code, Codex, and Hermes; Cursor and OpenClaw are roadmap-only. - -End-to-end: detect → install hooks (reversible) → launch with `WAGGLE_WORKSPACE_ID` env → hook captures → shim emitter → bus → bridge → UI. Rollback tag: `checkpoint/pre-ai-os-2026-05-20`. AI-OS exploration doc: `docs/plans/AI-OS-EXPLORATION-2026-05-19.md`. - -### Open Work -| # | File | What | -|---|---|---| -| 1 | Spawn Agent + Dock wiring | P36 already wired in `Dock.tsx`+`Desktop.tsx`; P35 third-tier fallback (LiteLLM → runtime model → provider catalogs) landed `14942be`. Residual: runtime verification on a clean install. | -| 2 | Light mode finish | P40/P41 + CR-2 — semantic-token migration is done (no hive-950 references except a comment); remaining issues are render-time fine-tuning (BootScreen visual polish + a few header-styling judgments) that need a binary build to validate. | -| 3 | External-tool release cohort | **Windows Solo scope fixed 2026-08-02.** Claude Code, Codex, and Hermes are the in-scope agent-integration cohort. Cursor and OpenClaw implementations remain in-tree as roadmap work and are fail-closed in production surfaces. Claude Desktop, Codex Desktop, and Hermes Desktop are convenience launch surfaces, not separate agent-acceptance targets. | - -**Closed during May 2026 backlog sweep:** -- ✅ OW-6 PersonaSwitcher two-tier — shipped via M-01 (`PersonaSwitcher.tsx` + `lib/persona-tier.ts` + `lib/persona-tooltip.ts`); 26/26 tests passing -- ✅ CR-7 CLAUDE.md §10 update (this entry) -- ✅ P35 Spawn Agent "no models available" (`14942be`) -- ✅ QW-1..QW-5 quick wins (all already shipped per `grep` verification) -- ✅ CR-2 hive-950 → semantic tokens (only comment-level refs remain) -- ✅ M7 Stripe products — both test (`acct_1SzHlbC0mmjh4oEM`) and live (`CNCrMQy1f7`) accounts hold the full 2 products × 2 prices (monthly + annual) with `pro_monthly` / `pro_annual` / `teams_monthly` / `teams_annual` lookup keys. Verified via `stripe products list` + `stripe prices list`. Live price IDs documented in `docs/launch/drafts/2026-05-12-apps-www-deployment-readiness.md`. _Note (Solo-vs-Team collapse 2026-07-05): the PRO products/prices are **retained in Stripe for legacy-sub servicing only** — no new PRO checkout is offered. Only TEAMS is an active checkout price._ -- ✅ E-10 Stripe tier-enforcement wiring — webhook handler was already complete (signature + idempotency + 3 event handlers in `packages/server/src/stripe/webhook.ts`); session closed the residual gap by extending `tierFromPriceId()` in `packages/server/src/stripe/index.ts` to resolve the full 4-var contract (`STRIPE_PRICE_PRO_MONTHLY` / `_ANNUAL` / `STRIPE_PRICE_TEAMS_MONTHLY` / `_ANNUAL`) alongside legacy single-vars + `STRIPE_PRICE_BASIC`. 17/17 webhook tests green; annual subscriptions now resolve through the webhook. _Note (Solo-vs-Team collapse 2026-07-05): `tierFromPriceId()` still reads the legacy PRO/BASIC price envs, but now maps them → `'FREE'` (Solo) so a legacy PRO subscriber lands on Solo rather than a removed tier. Only TEAMS resolves to a paid tier._ -- ✅ M2 Claude export — `data-ffbb9f0b-…batch-0000.zip` (30 MB) on Desktop\MEMORIES\Claude\, dated 2026-04-17. Ready for E-11 ingestion. -- ✅ M3 Gemini export — `takeout-20260416T224803Z-3-001.zip` (437 MB) on Desktop\MEMORIES\Google\, dated 2026-04-17. Ready for E-11 ingestion. -- ⏭️ M1 ChatGPT export — skipped by Marko 2026-05-21 (export emails never arrived after multiple requests). -- ⏭️ M4 Perplexity export — skipped by Marko 2026-05-21 (research-burst usage; marginal corpus contribution). -- ✅ M6 judge roster — Opus 4.7 / GPT-5.4 / Gemini 2.5 Pro / Haiku 4.5 locked 2026-05-21. -- ✅ C-1 LoCoMo Memory SOTA — **CURRENT CANONICAL: 86.49% overall** (7-lane W4, Memori *same-judge* protocol — GPT-4.1-mini answerer+judge, N=1540), **+4.54pp over Memori 81.95** (z=4.64, p<10⁻⁵), leading/tying every category. Mem0 re-run on our ruler = **73.96** overall (**temporal +30.8pp** landslide; write-time dating vs Mem0 ingestion-time). **CORRECTED 2026-07-01: the prior 87.66% did NOT reproduce on a fresh judge pass (stale-verdict-replay inflation; archived-substrate 85.19% / current 86.49%). 86.49% is the fresh reproducible number** — pinned + offline-verifiable at [`benchmarks/results/locomo-sota-2026-06/`](benchmarks/results/locomo-sota-2026-06/) (`node recount.mjs` → 1332/1540); record in `docs/analysis/locomo-87.66-vs-85.26-integrity-2026-06-30.md`. Paper/arXiv in [`docs/paper/`](docs/paper/); OSS `marolinik/hive-mind` @ `bc4eba1`, PR #14. - - ~~_SUPERSEDED (v5 self-judge, N=320, 2026-05-11): 73.1% Opus 4.7 / 73.4% Qwen3.6, +4.6pp over Mem0 paper; trio-strict 67.8% AND-of-3. The 73.1/73.4 self-judge convergence + 67.8 trio-strict remain valid as the conservative v5-arc framing but are no longer the headline. See `D:/Projects/hive-mind-test/scripts/locomo/data/reports/RESULT-v5-2026-05-11.md`._~~ -- ✅ C-2 Substrate Claim — done 2026-04-25: Stage 3 v6 N=400, Fisher one-sided p = 8.07 × 10⁻¹⁸, +19.25pp retrieval-vs-no-context lift. "GEPA Full-System canary" expansion explicitly DROPPED 2026-04-30 per PM strategic reset. See `D:/Projects/waggle-os-gaia2-wt/benchmarks/results/stage3-n400-v6-final-analysis.md`. - -### Closed 2026-05-21 (E-14 + audit-trail surfacing) - -- ✅ **E-14 hive-mind v0.3.0 promotion** — shipped on `marolinik/hive-mind` in 3 commits + 1 annotated tag (`b5c1e8f` wiki-web port, `842f390` benchmarks/locomo, `507e0cf` release commit, tag `v0.3.0`). README + CHANGELOG refreshed, 9 versions at 0.3.0, npm install + tsc build clean, vitest 308/312 (4 pre-existing dispatch.test.ts failures documented as v0.3.x followup — same on baseline `20bce16` so not session-induced). Substrate-claim evidence (LoCoMo 73.1% + Fisher p=8.07e-18) now publicly visible. Unblocks S-1 (OSS launch timing) — "before Waggle" is the default since the substrate claim is now public. - -### New open work surfaced 2026-05-21 - -| # | Item | What | -|---|---|---| -| C-3 (reframed) | Full GAIA 2 Phase 4 benchmark | Phase 3 closed in HALT 2026-04-30 (commit `104aa5a` in `waggle-os-gaia2-wt`). Probe showed $4.09/invocation (9-31× over original estimate), narrow-proxy adapter approach economically non-viable. Phase 4 needs Docker + ARE proper agentic execution environment + new adapter strategy. Real engineering arc — scope + budget recalibrate pending Phase 4 design. | - -For the full polish+launch backlog see `docs/plans/BACKLOG-CONSOLIDATED-2026-04-17.md` (~145 items; ~50% are stale-but-done per the May 2026 verification sweep) and the AI-OS arc in `docs/plans/AI-OS-EXPLORATION-2026-05-19.md`. - ---- - -## 11. Glossary - -| Term | Definition | -|---|---| -| Hive DS | Waggle design system — honey/hive-950/accent tokens in `waggle-theme.css` | -| FrameStore | SQLite-backed memory frame storage (`packages/hive-mind-core/src/mind/frames.ts`) | -| HybridSearch | Vector + keyword search (`packages/hive-mind-core/src/mind/search.ts`) | -| KnowledgeGraph | Entity-relation graph (`packages/hive-mind-core/src/mind/knowledge.ts`) | -| IdentityLayer | Personal identity persistence (`packages/hive-mind-core/src/mind/identity.ts`) | -| AwarenessLayer | Active task/state tracking (`packages/hive-mind-core/src/mind/awareness.ts`) | -| Cognify | Memory extraction pipeline (`packages/agent/src/cognify.ts`) | -| Harvest | Conversation/file ingestion (`packages/hive-mind-core/src/harvest/`) | -| Mind | Per-workspace persistence layer (`packages/hive-mind-core/src/mind/`) | -| BEHAVIORAL_SPEC | Core agent rules (`packages/agent/src/behavioral-spec.ts`) | -| Sidecar | Node.js Fastify server bundled into Tauri (`/sidecar`) | -| KVARK | Egzakta sovereign enterprise AI — top of the Waggle funnel | -| LiteLLM | Optional server/team deployment proxy config (`litellm-config.yaml`); Windows Solo uses the bundled no-Python proxy and smart router | -| WaggleDance | Multi-agent coordination package (`packages/waggle-dance`) | -| Weaver | Memory consolidation and session-skill extraction engine (`packages/weaver`) | -| Evolution | Self-improvement subsystem (`evolution-*.ts`, `judge.ts`, `iterative-optimizer.ts`) | -| applyPersonaToolFilter / filterMcpToolsForPersona | Enforced local and MCP per-persona allowlist/denylist filtering (`packages/server/src/local/persona-tool-filter.ts`) | - ---- - -Maintained by Marko Markovic · Egzakta Group · April 2026 -waggle-os.ai · www.kvark.ai +- Code, comments, commit messages and repository docs are in English. +- Log defects of the commercial product in `docs/oss/upstream-fixes.md` in the same commit + as the fix (`AGENTS.md`, section 3, rule 9).