vibeostheog 0.15.23 → 0.16.0

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 0.16.0
+- feat: dopamine-style footer + natural language system directives
+- feat: dopamine-style footer + natural language system directives
+- feat: turn-aware compaction directive at turn 7+
+- feat: add forensic/web-research modes + 1084-datapoint benchmark
+- fix: flash icon only when API connected, unified [VIBE→MODE⚡] format
+- docs: Security section + Context7 cost optimization docs
+- docs: add Security section with API token emphasis and Context7 cost optimization docs
+- docs: persist all benchmark data + compaction research
+- docs: reformat README as user-facing PM doc, move internals to AGENTS.md, cleanup .gitignore
+Merge pull request #35 from DrunkkToys/refactor/simplify-chat-transform
+readme: center VIBE autoswitching as the core value proposition
+Revert "fix: add system prompt cache savings tracking"
+
+
 ## 0.15.23
 - feat: add trinity api-token command to inject VIBEOS_API_TOKEN
 

package/README.md

@@ -1,286 +1,175 @@
 # vibeOS for OpenCode
 
-Cost-aware delegation and policy plugin for OpenCode Desktop.
+VIBE is a smart model router for OpenCode Desktop. It automatically selects and switches between brain, medium, and cheap model tiers based on the task at hand — expensive models handle orchestration while cost-effective models execute implementation work. No manual slot-picking needed.
 
-vibeOS helps keep expensive model usage under control by enforcing delegation behavior, tracking savings, and exposing runtime controls through the `trinity` tool.
+The core is the VIBE autoswitcher: a decision engine that routes each request to the right tier based on context, enforcement policy, and session state. You stay in control via the `trinity` tool set, but the default workflow is zero-config.
 
-## Version
+Beyond routing, vibeOS tracks savings from tier-switching, enforces delegation policies, and provides real-time visibility through a live status footer and web dashboard.
 
-Current package version: `0.14.1`
+## Savings Categories
 
-## What It Does
-
-- Tracks estimated savings from delegation warnings and enforcement events.
-- Tracks cache savings as a separate persisted category when scratchpad cache hits are observed.
-- Adds a live footer to assistant outputs with model split, cumulative savings, and trend arrow.
-- Provides `trinity` runtime controls for slot switching, enforcement toggles, audits, and diagnostics.
-- Adds per-session model locking: prevents the plugin from auto-switching models when the user changes the model in the OpenCode GUI (`trinity lock on|off`).
-- Adds optional flow checks and TDD skeleton enforcement.
-- Adds project guard: ensures AGENTS.md and README.md exist and stay protected in every project.
-- Adds report and research-audit tooling.
-- Learns recurring struggle and routine patterns per project, with `trinity patterns` inspection and `trinity patterns clear`.
-- Stress mitigation pipeline: detects user stress signals, shows live stress gauge in footer, injects protective system prompts, and upgrades Task tier when user is stressed.
-- vibeOS MCP server with HTTP API for extended tool capabilities (trinity, reports, session metrics, diagnostics).
-- TUI dashboard sidebar plugin for real-time plugin status and controls.
-- **Web dashboard** — SolidJS SPA served via standalone server (`npm run dashboard`) or embedded in the MCP server. Real-time SSE push updates at `http://127.0.0.1:3333`.
-- Worker-to-Brain (WBP) protocol synthesizes delegated task output directly in assistant chat.
-- **Remote API protection**: Core algorithms run on a self-hosted API server (`api.vibetheog.com`) with token-based authentication. Non-paying seats can be deactivated, immediately revoking all API tokens and falling back to local degraded mode.
-
-## Remote API Protection
-
-vibeOS protects its core algorithms by serving them from a self-hosted API server rather than bundling them entirely in the plugin:
-
-| Algorithm | Endpoint | Description |
-|---|---|---|---|
-| Delegation enforcement | `POST /api/v1/delegate/check` | Model cost calculation, block/warn routing |
-| Model tier routing | `POST /api/v1/route/model` | Tier classification, stress-aware routing |
-| Stress scoring | `POST /api/v1/stress/score` | NLP stress signal detection |
-| Blackbox engine | `POST /api/v1/blackbox/analyze` | Dialogue trajectory, loop detection, pivot/switch, outcome tracking |
-| Blackbox calibration | `POST /api/v1/blackbox/calibrate` | Auto-tune thresholds from session outcomes |
-| Blackbox calibration state | `GET /api/v1/blackbox/calibration` | Read calibrated weights per project |
-| Blackbox outcome | `POST /api/v1/blackbox/outcome` | Record session satisfaction outcome |
-| Blackbox project sessions | `GET /api/v1/blackbox/project-sessions` | List cross-session history per project |
-| TDD skeleton gen | `POST /api/v1/tdd/skeleton` | Multi-language test generation |
-| Pattern learner | `POST /api/v1/patterns/observe` | Friction/routine detection |
-| Model pricing | `POST /api/v1/pricing/fetch` | Dynamic OpenRouter pricing cache |
-| Context compression | `POST /api/v1/compress/context` | Bullet-point extraction |
-
-### Environment Variables
-
-```
-VIBEOS_API_URL=https://api.vibetheog.com   # API server URL (default: https://api.vibetheog.com)
-VIBEOS_API_TOKEN=vos_...                    # Your API token (required for remote mode)
-VIBEOS_API_ENABLED=true                     # Set to "false" to use local-only mode
-CLAUDE_CREDIT_PERCENT=150                   # Override credit percentage (default: 100)
-CLAUDE_CONTEXT7_AVAILABLE=true              # Set to enable context7 cost optimization
-CLAUDE_SCRATCHPAD_MAX_AGE_SEC=86400         # Scratchpad cache lifetime in seconds
-VIBEOS_MCP_PORT=3001                        # MCP server port (default: 3001)
-```
+- **Delegation savings** — Estimated cost avoided by routing tasks to cheaper models.
+- **Cache savings** — Cost avoided from scratchpad cache hits.
 
-When `VIBEOS_API_TOKEN` is not set or `VIBEOS_API_ENABLED=false`, the plugin runs in local-only mode with all algorithms bundled. When a valid token is provided, core algorithms are offloaded to the remote API.
+Both are summed in the live footer and persisted in \`~/.claude/delegation-state.json\` across sessions.
 
-### Seat & Token Management
+## What It Does
 
-The API server manages licenses via seats:
+- **Smart delegation** — Blocks direct write/edit on high-tier models and routes work to cheaper subagents
+- **Cost tracking** — Tracks estimated savings from delegation events and cache hits, displayed in a live footer
+- **trinity commands** — Runtime controls for model switching, enforcement toggles, audits, and diagnostics
+- **Flow enforcer** — Validates write/edit patterns against project rules; optionally extracts TODOs/FIXMEs
+- **TDD enforcer** — Auto-creates test skeletons for changed source files; strict mode makes TODO tests fail loudly
+- **Project guard** — Protects AGENTS.md and README.md in every project with auto-regeneration
+- **Pattern learner** — Detects recurring friction and routine patterns per project, surfaces via `trinity patterns`
+- **Stress mitigation** — Detects user stress signals, adjusts tier routing, and injects protective prompts
+- **Model locking** — Prevents auto-switching when model is changed in the OpenCode GUI (`trinity lock`)
+- **Report & audit** — `report-save`, `report-list`, `report-read`, and `research-audit` tools
+- **Worker-to-Brain protocol** — Delegates implementation tasks to cheaper subagents, synthesizes results in-chat
+- **Web dashboard** — Real-time status, savings, stress gauge, and controls via browser
+- **TUI sidebar** — Plugin status and controls via OpenCode sidebar plugin
+- **Blackbox decision engine** — Dialogue trajectory tracking with loop prevention, pivot detection, and outcome tracking
 
-- **Create a seat + token** (WordPress integration):  
-  `POST /admin/seats` with `{ "name": "...", "email": "...", "with_token": "label" }`
+## Install
 
-- **Suspend a seat** (non-paying customer):  
-  `PATCH /admin/seats/:id` with `{ "status": "suspended" }`  
-  This immediately revokes all API tokens for that seat. The plugin falls back to local degraded mode.
+### npm (Recommended)
 
-- **Reactivate a seat**:  
-  `PATCH /admin/seats/:id` with `{ "status": "active" }`
+```bash
+npm install vibeOS
+```
 
-## Runtime Model Slots
+Register in `~/.config/opencode/opencode.json`:
 
-Slots are configured in `~/.claude/model-tiers.json`:
+```json
+"plugins": [
+  { "id": "vibeOS", "path": "node_modules/vibeOS/src/index.js" }
+]
+```
 
-- `brain`
-- `medium`
-- `cheap`
+### Local Plugin File
 
-On startup, the plugin detects the active model/slot from `model-tiers.json`. No automatic slot switching occurs; use `trinity set <slot>` or `trinity rebuild` to change slots.
+Copy the plugin and lib files to `~/.config/opencode/plugins/`. See the repository for the complete file list.
 
-## Savings Categories (Persisted)
+Register in `~/.config/opencode/opencode.json`:
 
-State file: `~/.claude/delegation-state.json`
+```json
+"plugins": [
+  { "id": "vibeOS", "path": "~/.config/opencode/plugins/vibeOS.js" }
+]
+```
 
-- Delegation savings:
-  - `sessions[...].warns[].est_savings_usd`
-  - aggregated into footer totals
-- Cache savings:
-  - `sessions[...].cache_savings_usd`
-  - `lifetime.cache_savings_usd`
-  - optional `sessions[...].cache_hits[]` audit entries
-- Context7 missed-savings tracker:
-  - `lifetime.missed_context7_usd`
+Restart OpenCode Desktop. The plugin auto-creates its configuration on first run.
+
+## trinity Commands
+
+| Command | Description |
+|---|---|
+| `trinity status` | Show current plugin state |
+| `trinity set brain\|medium\|cheap` | Switch model slot |
+| `trinity brain\|medium\|cheap` | Shorthand slot switch |
+| `trinity enable` / `trinity disable` | Toggle plugin on/off |
+| `trinity thinking full\|brief\|off` | Set reasoning depth |
+| `trinity enforce on\|off` | Toggle delegation enforcement |
+| `trinity lock on\|off` | Toggle model locking |
+| `trinity flow on\|off` | Toggle flow enforcer |
+| `trinity flow enforce on\|off` | Toggle auto TODO extraction |
+| `trinity tdd on\|off` | Toggle test skeleton gen |
+| `trinity tdd strict on\|off` | Toggle strict mode |
+| `trinity tdd quality on\|off` | Toggle quality mode |
+| `trinity blackbox on\|off\|status\|reset` | Decision engine controls |
+| `trinity project` | Per-project analytics |
+| `trinity patterns` / `trinity patterns clear` | Inspect / clear patterns |
+| `trinity guard` | Regenerate project guard files |
+| `trinity diagnose` | Run diagnostics |
+| `trinity rebuild` | Auto-detect available models |
+| `trinity help` | Command reference |
 
 ## Footer Format
 
 Typical output footer:
 
-`— [model route] | VibeTheOG: <total> saved <arrow> —`
-
-Example (with savings):
-
-`— [🧠 deepseek-v4-flash → ⚙ deepseek-chat] | VibeTheOG: 0.01 saved → —`
-
-Example (no savings yet, tier label only):
-
-`— [⚙ Mid] —`
-
-## `trinity` Tool Commands
-
-Main commands:
-
-- `trinity status`
-- `trinity set brain|medium|cheap`
-- `trinity brain|medium|cheap`
-- `trinity enable` / `trinity disable`
-- `trinity thinking full|brief|off`
-- `trinity enforce` / `trinity enforce on|off`
-- `trinity lock on|off` / `trinity lock`
-- `trinity flow on|off` / `trinity flow enforce on|off` / `trinity flow`
-- `trinity tdd on|off` / `trinity tdd strict on|off` / `trinity tdd quality on|off` / `trinity tdd`
-- `trinity project`
-- `trinity patterns`
-- `trinity patterns clear`
-- `trinity patterns suggest`
-- `trinity repair-state`
-- `trinity guard`
-- `trinity diagnose`
-- `trinity rebuild`
-- `trinity help`
-
-## Optional Enforcement Modules
-
-- Delegation enforcement:
-  - Blocks direct `write`/`edit`/`notebookedit` on high-tier brain when enabled.
-  - Adds user-visible enforcement notes.
-- Flow enforcer:
-  - Rule checks for write/edit patterns.
-  - Optional TODO/FIXME extraction queue when flow enforcement is enabled.
-- TDD enforcer:
-  - Auto-creates skeleton tests for changed source files when enabled.
-  - Strict mode is ON by default: TODO tests fail loudly until implemented.
-- Project Guard:
-  - On session init, checks if AGENTS.md and README.md exist in the project root.
-  - Auto-creates AGENTS.md with protective rules (LLM must ask before modifying code).
-  - Auto-creates README.md with tech stack auto-detection and feature stubs.
-  - Flow rules warn/flag on write/edit to these protected files.
-  - System prompt injects directive to maintain both files.
-  - `trinity guard` command regenerates both files on demand.
-
-## Reports and Audit Tools
-
-- `research-audit`
-- `report-save`
-- `report-list`
-- `report-read`
-
-These use `~/.claude/reports` and project memory in `~/.claude/project-states.json`.
-
-## Pattern Learning
-
-- Detects repeated friction signals and recurring successful routines from session behavior.
-- Stores per-project pattern memory in `~/.claude/project-states.json`.
-- Promotes patterns after repeated confirmation across sessions and surfaces them via `trinity patterns`.
-
-## Blackbox Decision Engine
-
-The blackbox tracks dialogue trajectory per-session and per-project, providing real-time decision state insights:
-
-**Enabled by default.**
-
-- **Resolution tracking**: Classifies each session into one of 7 sub-regimes (INIT, DIVERGENT, EXPLORING, REFINING, CONVERGING, CLOSED, LOOPING) based on entropy trends, action consistency, feature contradiction, and embedding drift.
-- **Real feature extraction**: Derives 11 features from each user message — message length, word count, question ratio, code blocks, urgency signals, sentiment, complexity, repetition, and instruction density.
-- **Loop prevention**: Detects when the conversation is going in circles and injects escalating system prompt interventions (gentle → suggestive → assertive → escalated) to break the loop.
-- **PIVOT/SWITCH detection**: Recognizes when the user changes context outside the current project scope and injects scope-confirmation directives.
-- **Outcome tracking**: Detects satisfaction signals from assistant responses (positive: "thanks/that works/perfect"; negative: "broken/still failing/wrong") and records them for calibration.
-- **Cross-session continuity**: State persists per project fingerprint in `~/.claude/blackbox-state.json` and remotely in SQLite, allowing resolution state to carry across terminal restarts.
-- **Online calibration**: The API server aggregates session outcomes and auto-tunes loop detection, momentum, and closure thresholds per project via `POST /api/v1/blackbox/calibrate`.
-
-Commands:
-- `trinity blackbox on` — Enable the decision engine
-- `trinity blackbox off` — Disable the decision engine
-- `trinity blackbox status` — View current resolution, sub-regime, momentum, loop state, and project history
-- `trinity blackbox reset` — Clear the resolution tracker for the current session
+```
+— [model route] | VibeTheOG: <total> saved <arrow> —
+```
 
+The footer shows model split, cumulative savings, stress gauge, and trend arrow.
 
-The blackbox injects a decision directive into system prompts showing current resolution state, intent volatility, and continuity. When looping or pivoting is detected, stronger intervention directives are injected to guide the model.
+## Web Dashboard
 
-### Session Workflow Phases
+```bash
+npm run build:dashboard   # Build the SPA
+npm run dashboard         # Start server on http://127.0.0.1:3333
+```
 
-The meta-controller maps detected sub-regimes to optimization modes, which are the authority over all plugin settings. Each turn, `syncControlSettings()` writes the mode's control vector to `model-tiers.json`, auto-toggling enforcement, flow, TDD, and thinking level:
+Displays model split, savings, session history, stress gauge, trinity controls, reports, and blackbox state with SSE push updates every 1.5s.
 
-| Regime | Mode | Enforce | Flow | TDD | Tier | Think |
-|---|---|---|---|---|---|---|
-| INIT | budget | relaxed | audit | lazy | cheap | off |
-| EXPLORING / DIVERGENT | budget | relaxed | audit | lazy | cheap | off |
-| REFINING | budget | relaxed | audit | lazy | cheap | off |
-| CONVERGING / CLOSED | quality | strict | strict | quality | brain | full |
-| LOOPING | speed | relaxed | audit | lazy | medium | off |
+## Security
 
-**Stress override**: When user stress exceeds 1.5, any regime escalates to `quality` mode — enforcement tightens, brain tier activates. Settings are re-synced every turn; mode is the sole authority. Manual `trinity enforce on/off` still works until the next turn re-evaluates.
+The API token (`VIBEOS_API_TOKEN`) acts as a **password** for your vibeOS seat. Treat it with the same care as any credential.
 
-When the blackbox is disabled, a lightweight `classifyTurnSimple()` fallback inspects user message patterns:
-- Q&A patterns (`"how"`, `"what"`, `"explain"`) → EXPLORING (relaxed)
-- Implementation patterns (`"write"`, `"fix"`, `"implement"`) → REFINING (normal)
+- **Token-based seat auth** — Each token is bound to a seat. Suspending a seat immediately revokes all associated tokens.
+- **Graceful degradation** — If the token is revoked or the API is unreachable, the plugin falls back to local-only mode with bundled algorithms. No functionality is lost; only remote-optimized routing is disabled.
+- **Never commit tokens** — `.env.production` and `PRODUCTION-CREDENTIALS.md` are gitignored. Do not share or hardcode tokens in source files.
+- **Token rotation** — Generate a new token and update `VIBEOS_API_TOKEN` if you suspect a leak. Old tokens are invalidated immediately on seat suspension.
+- **Local-only mode** — Without an API token, all algorithms run locally. Set `VIBEOS_API_ENABLED=false` to explicitly disable all remote calls.
 
-## Install
+## Context7 Cost Optimization
 
-### npm (Recommended)
+[context7](https://upstash.com/docs/context7) is an MCP tool that resolves library/framework documentation queries at a fraction of the cost of WebFetch (~$0.06/turn saved).
 
-Published to npm as `vibeOS`:
+**Install it once:**
 
 ```bash
-npm install vibeOS
-```
-
-Then register in `~/.config/opencode/opencode.json`:
-```json
-"plugins": [
-  { "id": "vibeOS", "path": "node_modules/vibeOS/src/index.js" }
-]
-```
-
-### Local Plugin File
-
-For OpenCode Desktop local plugin usage, copy these files to `~/.config/opencode/plugins/`:
-
-```
-cp src/index.js                    ~/.config/opencode/plugins/vibeOS.js
-cp src/vibeOS-lib/flow-enforcer.js ~/.config/opencode/plugins/vibeOS-lib/flow-enforcer.js
-cp src/vibeOS-lib/session-metrics.js ~/.config/opencode/plugins/vibeOS-lib/session-metrics.js
-cp src/vibeOS-lib/flow-rules.json  ~/.config/opencode/plugins/vibeOS-lib/flow-rules.json
-cp src/utils/cost-formatter.js     ~/.config/opencode/plugins/vibeOS-lib/cost-formatter.js
-cp src/utils/math.js               ~/.config/opencode/plugins/vibeOS-lib/math.js
-cp src/utils/timer.js              ~/.config/opencode/plugins/vibeOS-lib/timer.js
-```
-
-Then register the plugin in `~/.config/opencode/opencode.json`:
-
-```json
-"plugins": [
-  { "id": "vibeOS", "path": "~/.config/opencode/plugins/vibeOS.js" }
-]
+claude mcp add context7 npx @upstash/context7-mcp
 ```
 
-Restart OpenCode Desktop. The plugin auto-creates `~/.claude/model-tiers.json` on first run.
+### How vibeOS uses context7
 
-## Web Dashboard
+- **Auto-detection** — At module load, vibeOS scans `~/.claude/settings.json`, `~/.claude.json`, `opencode.json`, and `~/.config/opencode/` for a `context7` reference. No manual config needed.
+- **System prompt injection** — When context7 is detected, a cost-policy directive is injected into every system prompt instructing the model to prefer `mcp__context7__resolve-library-id` and `mcp__context7__get-library-docs` over WebFetch/WebSearch for documentation URLs.
+- **Urgency levels** — Controlled by the blackbox engine:
+  - `required` (strict/TDD-strict mode) — context7 is mandatory this turn.
+  - `preferred` (default) — context7 is encouraged but not forced.
+  - `optional` (relaxed mode) — context7 is a nice-to-have.
+- **Docs nudge** — If context7 is not installed and the model uses WebFetch on a documentation URL (docs.*, readthedocs, MDN, npmjs, pypi, crates.io, pkg.go.dev, etc.), vibeOS logs a one-time install suggestion and tracks the missed savings.
+- **Savings tracking** — Every docs URL fetched via WebFetch instead of context7 is recorded as `missed_context7_usd` in `~/.claude/delegation-state.json`. Accumulated misses appear in `trinity project` analytics with an installation suggestion when bypasses exceed 3.
 
-Open `http://127.0.0.1:3333` in your browser after starting the server.
+### Force-enable detection
 
 ```bash
-npm run build:dashboard   # Build the SPA (one-time)
-npm run dashboard         # Start standalone server on :3333
-npm run dev:dashboard     # Vite dev server on :5173 with hot-reload
+export CLAUDE_CONTEXT7_AVAILABLE=true
 ```
 
-Features: model split, savings, sessions, stress gauge, trinity controls, reports, blackbox state. SSE push updates every 1.5s.
+Use this when context7 is configured but the auto-scan misses it (unusual paths, remote configs, or runtime-loaded MCP definitions).
 
-## Build
+## Environment Variables
 
-- `npm run build`
-- `npm run build:dashboard` (build the web dashboard SPA)
+| Variable | Default | Description |
+|---|---|---|
+| `VIBEOS_API_URL` | `https://api.vibetheog.com` | API server URL |
+| `VIBEOS_API_TOKEN` | — | **API token (password). Protect like a credential.** Required for remote mode. If compromised, rotate immediately via seat suspension. |
+| `VIBEOS_API_ENABLED` | `true` | Set to `false` for local-only mode |
+| `CLAUDE_CREDIT_PERCENT` | `100` | Credit percentage override |
+| `CLAUDE_CONTEXT7_AVAILABLE` | — | Enable context7 cost optimization |
+| `CLAUDE_SCRATCHPAD_MAX_AGE_SEC` | `86400` | Scratchpad cache lifetime |
+| `VIBEOS_MCP_PORT` | `3001` | MCP server port |
 
-`npm run build` compiles TypeScript source-of-truth modules and syncs generated JS artifacts used by runtime.
+Without an API token, the plugin runs in local-only mode with all algorithms bundled locally.
 
-## CI/CD
-
-GitHub Actions workflows are in `.github/workflows/`:
+## Runtime Model Slots
 
-- **CI** (`.github/workflows/ci.yml`): Runs on every push/PR to `main`/`master`. Executes typecheck, syntax check, test suite, TypeScript audit, and build validation.
+Tier configuration in `~/.claude/model-tiers.json`:
 
-- **Release** (`.github/workflows/release.yml`): Manual trigger via GitHub Actions UI (`workflow_dispatch`). Prompts for version bump type (patch/minor/major), then runs tests, builds, and executes `scripts/release.mjs --yes --ci` which bumps version, updates changelog, commits/tags/pushes, creates a GitHub Release, and publishes to npm.
+| Slot | Purpose |
+|---|---|
+| `brain` | High-tier model for orchestration |
+| `medium` | Mid-tier for moderate tasks |
+| `cheap` | Low-tier for delegation subagents |
 
-Before using the release workflow, add an `NPM_TOKEN` secret to the repository with an npm automation token that has publish permissions for the `vibeOS` package.
+Use `trinity set brain|medium|cheap` or `trinity rebuild` to configure.
 
 ## Known Limitations
 
-- OpenCode runtime behavior can vary by version for per-task model override handling.
-- Some legacy tests in this repo are older than current enforcement defaults and may fail due to changed policy semantics rather than runtime breakage.
-- Savings are estimates, not billing data.
+- OpenCode runtime behavior can vary by version.
+- Some test suite tests may fail due to policy semantic changes rather than actual breakage.
+- Savings displayed are estimates, not billing data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeostheog",
-  "version": "0.15.23",
+  "version": "0.16.0",
   "description": "Cost-aware delegation enforcer for OpenCode. Tracks model usage, routes Task subagents to cheaper tiers, surfaces cumulative savings in chat. Includes research audit, reporting framework, project memory, progressive scratchpad decadence, and trinity CLI for brain/medium/cheap slot switching.",
   "scripts": {
     "release": "node scripts/release.mjs",