openwolf-enhanced 1.9.3

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "openwolf-enhanced",
+  "version": "1.9.3",
+  "description": "Token-conscious AI brain for Claude Code projects — enhanced fork with bounded storage, self-maintenance (openwolf doctor), .wolfignore scoping, and tunable retention.",
+  "type": "module",
+  "bin": {
+    "openwolf": "./dist/bin/openwolf.js"
+  },
+  "scripts": {
+    "prebuild": "node -e \"const fs=require('fs');if(fs.existsSync('dist'))fs.rmSync('dist',{recursive:true})\"",
+    "build": "tsc && pnpm build:hooks && pnpm build:dashboard && chmod +x dist/bin/openwolf.js",
+    "postinstall": "chmod +x dist/bin/openwolf.js 2>/dev/null || true",
+    "build:hooks": "tsc -p tsconfig.hooks.json",
+    "build:dashboard": "cd src/dashboard/app && npx vite build --outDir ../../../dist/dashboard",
+    "dev": "tsc --watch",
+    "pretest": "tsc && tsc -p tsconfig.hooks.json",
+    "test": "node --test test/*.test.js",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "prepublishOnly": "node scripts/prepublish-guard.mjs"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
+    "express": "^5.2.1",
+    "node-cron": "^4.0.0",
+    "open": "^11.0.0",
+    "ws": "^8.21.0"
+  },
+  "optionalDependencies": {
+    "puppeteer-core": "^25.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.0",
+    "@types/express": "^5.0.0",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.5.12",
+    "@vitejs/plugin-react": "^6.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "recharts": "^3.9.0",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^7.0.0",
+    "vite": "^8.0.0",
+    "vitepress": "^1.6.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "Krynex Labs <info@krynexlabs.de> (https://krynexlabs.de)",
+  "contributors": [
+    "Cytostack Pvt Ltd (original OpenWolf)"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bassprofressor-lab/openwolf-enhanced.git"
+  },
+  "homepage": "https://github.com/bassprofressor-lab/openwolf-enhanced#readme",
+  "bugs": {
+    "url": "https://github.com/bassprofressor-lab/openwolf-enhanced/issues"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "context",
+    "token",
+    "openwolf",
+    "claude-code",
+    "developer-tools"
+  ],
+  "files": [
+    "dist/",
+    "src/templates/",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md",
+    "README.md"
+  ]
+}

package/src/templates/OPENWOLF.md

@@ -0,0 +1,147 @@
+# OpenWolf Operating Protocol
+
+You are working in an OpenWolf-managed project. These rules apply every turn.
+
+## STATUS.md — Single Source of Truth (READ FIRST)
+
+`.wolf/STATUS.md` is the **first file** you read when resuming a session. It captures, in one
+place: what's already done (✅), the current/next quest with acceptance criteria (🚀), the active
+architecture (📁), open pendencies (⚠️), and useful commands (🔧).
+
+1. **On session start / after `/clear`:** read `.wolf/STATUS.md` before anything else — it restores
+   context in ~1 read instead of stitching it together from memory.md, cerebrum.md and code.
+2. **When a quest finishes (or before you suggest `/clear`):** move completed items to ✅ and write
+   the next quest under 🚀, so the next session resumes cheaply.
+3. Keep it short and current — it is a handoff note, not a log (that's `memory.md`).
+
+## File Navigation
+
+1. Check `.wolf/anatomy.md` BEFORE reading any file. It has a 2-3 line description and token estimate for every file in the project.
+2. If the description in anatomy.md is sufficient for your task, do NOT read the full file.
+3. If a file is not in anatomy.md, search with Grep/Glob, then update anatomy.md with the new entry.
+
+## Code Generation
+
+1. Before generating code, read `.wolf/cerebrum.md` and respect every entry.
+2. Check the `## Do-Not-Repeat` section — these are past mistakes that must not recur.
+3. Follow all conventions in `## Key Learnings` and `## User Preferences`.
+
+## After Actions
+
+1. After every significant action, append a one-line entry to `.wolf/memory.md`:
+   `| HH:MM | description | file(s) | outcome | ~tokens |`
+2. After creating, deleting, or renaming files: update `.wolf/anatomy.md`.
+
+## Cerebrum Learning (MANDATORY — every session)
+
+OpenWolf's value comes from learning across sessions. You MUST update `.wolf/cerebrum.md` whenever you learn something useful. This is not optional.
+
+**Update `## User Preferences` when the user:**
+- Corrects your approach ("no, do it this way instead")
+- Expresses a style preference (naming, structure, formatting)
+- Shows a preferred workflow or tool choice
+- Rejects a suggestion — record what they preferred instead
+- Asks for more/less detail, verbosity, explanation
+
+**Update `## Key Learnings` when you discover:**
+- A project convention not obvious from the code (e.g., "tests go in __tests__/ not test/")
+- A framework-specific pattern this project uses
+- An API behavior that surprised you
+- A dependency quirk or version constraint
+- How modules connect or data flows through the system
+
+**Update `## Do-Not-Repeat` (with date) when:**
+- The user corrects a mistake you made
+- You try something that fails and find the right approach
+- You discover a gotcha that would trip up a fresh session
+
+**Update `## Decision Log` when:**
+- A significant architectural or technical choice is made
+- The user explains why they chose approach A over B
+- A trade-off is explicitly discussed
+
+**The bar is LOW.** If in doubt, add it. A cerebrum entry that's slightly redundant costs nothing. A missing entry means the next session repeats the same discovery process.
+
+## Bug Logging (MANDATORY)
+
+**Log a bug to `.wolf/buglog.json` whenever ANY of these happen:**
+- The user reports an error, bug, or problem
+- A test fails or a command produces an error
+- You fix something that was broken
+- You edit a file more than twice to get it right
+- An import, module, or dependency is missing or wrong
+- A runtime error, type error, or syntax error occurs
+- A build or lint command fails
+- A feature doesn't work as expected
+- You change error handling, try/catch blocks, or validation logic
+- The user says something "doesn't work", "is broken", or "shows wrong X"
+
+**Before fixing:** Read `.wolf/buglog.json` first — the fix may already be known.
+
+**After fixing:** ALWAYS append to `.wolf/buglog.json` with this structure:
+```json
+{
+  "id": "bug-NNN",
+  "timestamp": "ISO date",
+  "error_message": "exact error or user complaint",
+  "file": "file that was fixed",
+  "root_cause": "why it broke",
+  "fix": "what you changed to fix it",
+  "tags": ["relevant", "keywords"],
+  "related_bugs": [],
+  "occurrences": 1,
+  "last_seen": "ISO date"
+}
+```
+
+**The threshold is LOW.** When in doubt, log it. A false positive in the bug log costs nothing. A missed bug means repeating the same mistake later.
+
+## Token Discipline
+
+- Never re-read a file already read this session unless it was modified since.
+- Prefer anatomy.md descriptions over full file reads when possible.
+- Prefer targeted Grep over full file reads when searching for specific code.
+- If appending to a file, do not read the entire file first.
+
+## Design QC
+
+When the user asks you to check, evaluate, or improve the design/UI of their app:
+
+1. Run `openwolf designqc` via Bash to capture screenshots.
+   - The command auto-detects a running dev server, or starts one from package.json if needed
+   - Use `--url <url>` only if auto-detection fails
+   - The command saves compressed JPEG screenshots to `.wolf/designqc-captures/`
+   - Full pages are captured as sectioned viewport-height images (top, section2, ..., bottom)
+2. Read the captured screenshot images from `.wolf/designqc-captures/` using the Read tool.
+3. Evaluate the design against modern standards (Shadcn UI, Tailwind, clean React patterns):
+   - Spacing and whitespace consistency
+   - Typography hierarchy and readability
+   - Color contrast and accessibility (WCAG)
+   - Visual hierarchy and focal points
+   - Component consistency
+   - Whether the design looks "dull" or "white-coded" (generic, no personality)
+4. Provide specific, actionable feedback with fix suggestions.
+5. If the user approves, implement the fixes directly in their code.
+6. After fixes, re-run `openwolf designqc` to capture new screenshots and verify improvement.
+
+**Token awareness:** Each screenshot costs ~2500 tokens. The command compresses images (JPEG quality 70, max width 1200px) to minimize cost. For large apps, use `--routes / /specific-page` to limit captures.
+
+## Reframe — UI Framework Selection
+
+When the user asks to change, pick, migrate, or "reframe" their project's UI framework:
+
+1. Read `.wolf/reframe-frameworks.md` for the full framework knowledge base.
+2. Ask the user the decision questions from the file (current stack, priority, Tailwind usage, theme preference, app type). Stop early once the choice narrows to 1-2 options.
+3. Present a recommendation with reasoning based on the comparison matrix.
+4. Once the user confirms, use the selected framework's prompt from the file — **adapted to the actual project** using `.wolf/anatomy.md` for real file paths, routes, and components.
+5. Execute the migration: install dependencies, update config, refactor components.
+6. After migration, run `openwolf designqc` to verify the new look.
+
+**Do NOT read the entire reframe-frameworks.md into context upfront.** Read the decision questions and comparison matrix first (~50 lines). Only read the specific framework's prompt section after the user chooses.
+
+## Session End
+
+Before ending or when asked to wrap up:
+
+1. Write a session summary to `.wolf/memory.md`.
+2. Review the session: did you learn anything? Did the user correct you? Did you fix a bug? If yes, update `.wolf/cerebrum.md` and/or `.wolf/buglog.json`.

package/src/templates/STATUS.md

@@ -0,0 +1,48 @@
+# STATUS — {{PROJECT_NAME}}
+
+> Single source of truth for resuming work. **Read this FIRST** when starting a session.
+> Update it at the end of every quest so the next `/clear` resumes in a single read.
+>
+> Last updated: {{DATE}}
+
+---
+
+## ✅ Done
+
+- (nothing yet — move items here as quests complete)
+
+---
+
+## 🚀 Next phase
+
+**Goal:** _<what we're building next>_
+
+### Acceptance criteria
+1. _<concrete, user-visible outcome>_
+
+### Files to create / edit
+- _<path — purpose>_
+
+### Open decisions
+- _<question to resolve before coding>_
+
+---
+
+## 📁 Active architecture
+
+- **Stack:** _<frameworks / languages>_
+- **Entry points:** _<main files>_
+
+---
+
+## ⚠️ Pending / gotchas
+
+- _<known issues, blockers, things to remember>_
+
+---
+
+## 🔧 Useful commands
+
+```bash
+# add the commands you run most often here
+```

package/src/templates/anatomy.md

@@ -0,0 +1,5 @@
+# anatomy.md
+
+> Project structure index. Auto-maintained by OpenWolf hooks and daemon.
+> Run `openwolf scan` to generate, or wait for the first Claude Code session.
+> Status: Pending initial scan

package/src/templates/buglog.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "bugs": []
+}

package/src/templates/cerebrum.md

@@ -0,0 +1,22 @@
+# Cerebrum
+
+> OpenWolf's learning memory. Updated automatically as the AI learns from interactions.
+> Do not edit manually unless correcting an error.
+> Last updated: —
+
+## User Preferences
+
+<!-- How the user likes things done. Code style, tools, patterns, communication. -->
+
+## Key Learnings
+
+<!-- Project-specific conventions discovered during development. -->
+
+## Do-Not-Repeat
+
+<!-- Mistakes made and corrected. Each entry prevents the same mistake recurring. -->
+<!-- Format: [YYYY-MM-DD] Description of what went wrong and what to do instead. -->
+
+## Decision Log
+
+<!-- Significant technical decisions with rationale. Why X was chosen over Y. -->

package/src/templates/claude-md-snippet.md

@@ -0,0 +1,5 @@
+# OpenWolf
+
+@.wolf/OPENWOLF.md
+
+This project uses OpenWolf for context management. Read and follow .wolf/OPENWOLF.md every session. Check .wolf/cerebrum.md before generating code. Check .wolf/anatomy.md before reading files.

package/src/templates/claude-rules-openwolf.md

@@ -0,0 +1,17 @@
+---
+description: OpenWolf protocol enforcement — active on all files
+globs: **/*
+---
+
+- Read .wolf/STATUS.md FIRST when resuming a session — it holds the current quest, next steps, and decisions
+- Update .wolf/STATUS.md (✅ done / 🚀 next quest) when a quest finishes or before suggesting /clear
+- Check .wolf/anatomy.md before reading any project file
+- Check .wolf/cerebrum.md Do-Not-Repeat list before generating code
+- After writing or editing files, update .wolf/anatomy.md and append to .wolf/memory.md
+- After receiving a user correction, update .wolf/cerebrum.md immediately (Preferences, Learnings, or Do-Not-Repeat)
+- LEARN from every interaction: if you discover a convention, user preference, or project pattern, add it to .wolf/cerebrum.md. Low threshold — when in doubt, log it.
+- BEFORE fixing any bug or error: read .wolf/buglog.json for known fixes
+- AFTER fixing any bug, error, failed test, failed build, or user-reported problem: ALWAYS log to .wolf/buglog.json with error_message, root_cause, fix, and tags
+- If you edit a file more than twice in a session, that likely indicates a bug — log it to .wolf/buglog.json
+- When the user asks to check/evaluate UI design: run `openwolf designqc` to capture screenshots, then read them from .wolf/designqc-captures/
+- When the user asks to change/pick/migrate UI framework: read .wolf/reframe-frameworks.md, ask decision questions, recommend a framework, then execute with the framework's prompt

package/src/templates/config.json

@@ -0,0 +1,83 @@
+{
+  "version": 1,
+  "openwolf": {
+    "enabled": true,
+    "anatomy": {
+      "auto_scan_on_init": true,
+      "rescan_interval_hours": 6,
+      "max_description_length": 100,
+      "max_files": 500,
+      "exclude_patterns": [
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        ".wolf",
+        ".next",
+        ".nuxt",
+        "coverage",
+        "__pycache__",
+        ".cache",
+        "target",
+        ".vscode",
+        ".idea",
+        ".turbo",
+        ".vercel",
+        ".netlify",
+        ".output",
+        "*.min.js",
+        "*.min.css"
+      ]
+    },
+    "token_audit": {
+      "enabled": true,
+      "report_frequency": "weekly",
+      "waste_threshold_percent": 15,
+      "chars_per_token_code": 3.5,
+      "chars_per_token_prose": 4.0
+    },
+    "cron": {
+      "enabled": true,
+      "max_retry_attempts": 3,
+      "dead_letter_enabled": true,
+      "heartbeat_interval_minutes": 30,
+      "use_claude_p": true,
+      "api_key_env": null
+    },
+    "memory": {
+      "consolidation_after_days": 7,
+      "max_entries_before_consolidation": 200
+    },
+    "retention": {
+      "token_ledger_max_sessions": 200,
+      "session_io_max": 100,
+      "buglog_max_entries": 200,
+      "backups_keep": 10,
+      "memory_consolidate_after_days": 7,
+      "memory_max_bytes": 262144,
+      "daemon_log_max_bytes": 524288
+    },
+    "cerebrum": {
+      "max_tokens": 2000,
+      "reflection_frequency": "weekly"
+    },
+    "daemon": {
+      "port": 18790,
+      "log_level": "info"
+    },
+    "dashboard": {
+      "enabled": true,
+      "port": 18791,
+      "host": "127.0.0.1"
+    },
+    "designqc": {
+      "enabled": true,
+      "viewports": [
+        { "name": "desktop", "width": 1440, "height": 900 },
+        { "name": "mobile", "width": 375, "height": 812 }
+      ],
+      "max_screenshots": 6,
+      "chrome_path": null
+    }
+  }
+}

package/src/templates/cron-manifest.json

@@ -0,0 +1,97 @@
+{
+  "version": 1,
+  "tasks": [
+    {
+      "id": "anatomy-rescan",
+      "name": "Full anatomy rescan",
+      "schedule": "0 */6 * * *",
+      "description": "Re-scans project filesystem and reconciles anatomy.md",
+      "action": { "type": "scan_project" },
+      "retry": {
+        "max_attempts": 3,
+        "backoff": "exponential",
+        "base_delay_seconds": 30
+      },
+      "failsafe": {
+        "on_failure": "log_and_continue",
+        "alert_after_consecutive_failures": 2,
+        "dead_letter": true
+      },
+      "enabled": true
+    },
+    {
+      "id": "memory-consolidation",
+      "name": "Consolidate old memory",
+      "schedule": "0 2 * * *",
+      "description": "Compress memory.md entries older than 7 days",
+      "action": {
+        "type": "consolidate_memory",
+        "params": { "older_than_days": 7 }
+      },
+      "retry": {
+        "max_attempts": 2,
+        "backoff": "exponential",
+        "base_delay_seconds": 60
+      },
+      "failsafe": {
+        "on_failure": "skip_and_retry_next_cycle",
+        "dead_letter": false
+      },
+      "enabled": true
+    },
+    {
+      "id": "token-audit",
+      "name": "Token audit report",
+      "schedule": "0 0 * * 1",
+      "description": "Weekly waste pattern detection",
+      "action": { "type": "generate_token_report" },
+      "retry": {
+        "max_attempts": 2,
+        "backoff": "linear",
+        "base_delay_seconds": 60
+      },
+      "failsafe": { "on_failure": "log_and_continue", "dead_letter": true },
+      "enabled": true
+    },
+    {
+      "id": "cerebrum-reflection",
+      "name": "Cerebrum reflection",
+      "schedule": "0 3 * * 0",
+      "description": "Weekly AI review of cerebrum.md — prune stale entries, consolidate duplicates",
+      "action": {
+        "type": "ai_task",
+        "params": {
+          "prompt": "Review this cerebrum.md. Remove duplicate preferences (keep newer). Remove Do-Not-Repeat entries older than 90 days if no longer relevant. Consolidate Key Learnings that overlap. Keep the file under 2000 tokens. Return the cleaned file content only.",
+          "context_files": [".wolf/cerebrum.md"]
+        }
+      },
+      "retry": {
+        "max_attempts": 1,
+        "backoff": "none",
+        "base_delay_seconds": 0
+      },
+      "failsafe": { "on_failure": "log_and_continue", "dead_letter": false },
+      "enabled": true
+    },
+    {
+      "id": "project-suggestions",
+      "name": "AI suggestions",
+      "schedule": "0 4 * * 1",
+      "description": "Weekly AI analysis with project improvement suggestions",
+      "action": {
+        "type": "ai_task",
+        "params": {
+          "prompt": "Based on the recent memory entries and current project structure, provide: 1) Key achievements this week, 2) Code improvements to consider, 3) Logical next tasks, 4) Technical debt or risks. Be specific and actionable. Return as JSON: {achievements:[], improvements:[], next_tasks:[], risks:[]}",
+          "context_files": [".wolf/memory.md", ".wolf/anatomy.md"]
+        }
+      },
+      "retry": {
+        "max_attempts": 1,
+        "backoff": "none",
+        "base_delay_seconds": 0
+      },
+      "failsafe": { "on_failure": "log_and_continue", "dead_letter": false },
+      "enabled": true
+    }
+  ]
+}

package/src/templates/cron-state.json

@@ -0,0 +1,7 @@
+{
+  "last_heartbeat": null,
+  "engine_status": "initialized",
+  "execution_log": [],
+  "dead_letter_queue": [],
+  "upcoming": []
+}

package/src/templates/identity.md

@@ -0,0 +1,9 @@
+# Identity
+
+- **Name:** Wolf
+- **Role:** AI development assistant for this project
+- **Tone:** Direct, concise, technically precise
+- **Constraints:**
+  - Never modify .env or secret files without explicit user confirmation
+  - Never delete files without explicit user confirmation
+  - Always explain why before making architectural changes

package/src/templates/memory.md

@@ -0,0 +1,4 @@
+# Memory
+
+> Chronological action log. Hooks and AI append to this file automatically.
+> Old sessions are consolidated by the daemon weekly.