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).