loki-mode 5.51.0 → 5.52.1

package/docs/certification/03-advanced-patterns/lesson.md

@@ -0,0 +1,199 @@
+# Module 3: Advanced Patterns
+
+## Overview
+
+This module covers advanced patterns in Loki Mode: specialist review configuration, structured agent prompting, confidence-based routing, Chain-of-Verification, compound learning, and the event-driven hooks system.
+
+## Structured Agent Prompting
+
+Every Task dispatch in Loki Mode must include four sections: GOAL, CONSTRAINTS, CONTEXT, and OUTPUT. This template is documented in `skills/agents.md`.
+
+```python
+Task(
+    subagent_type="general-purpose",
+    model="opus",
+    description="Implement user registration API",
+    prompt="""
+## GOAL
+Create POST /api/users endpoint that registers new users.
+Success: Endpoint works, tests pass, matches OpenAPI spec.
+
+## CONSTRAINTS
+- Use bcrypt for password hashing (already in dependencies)
+- No new dependencies without approval
+- Response time < 200ms
+
+## CONTEXT
+- Existing auth pattern: src/auth/login.ts
+- OpenAPI spec: .loki/specs/openapi.yaml
+- User model: src/models/user.ts
+
+## OUTPUT
+- [ ] Endpoint implementation in src/routes/users.ts
+- [ ] Unit tests in tests/users.test.ts
+- [ ] Integration test in tests/integration/users.test.ts
+"""
+)
+```
+
+This structure ensures agents have clear success criteria, boundaries, necessary context, and defined deliverables.
+
+## Confidence-Based Routing
+
+Loki Mode uses confidence scores to determine how much oversight a task needs. This is enabled by default (`LOKI_CONFIDENCE_ROUTING=true`).
+
+| Confidence | Dispatch Strategy |
+|------------|-------------------|
+| >= 0.95 | Direct execution with fast-tier model, no review |
+| 0.70-0.95 | Direct execution + asynchronous review |
+| 0.40-0.70 | Supervisor orchestration, mandatory review |
+| < 0.40 | Flag for human decision |
+
+Confidence is calculated from five factors:
+
+- Requirement clarity (30%)
+- Similar past successes (20%)
+- Technical complexity match (25%)
+- Resource availability (15%)
+- Time pressure (10%)
+
+When confidence is below 0.40, the agent creates a `HUMAN_REVIEW_NEEDED` signal in `.loki/signals/` and blocks the task until human input is received.
+
+## Chain-of-Verification (CoVe)
+
+Based on research from arXiv 2309.11495, CoVe reduces hallucination by using factored, independent verification. The key insight: the verifier cannot see the original response, preventing confirmation bias.
+
+### The 4-Step Process
+
+1. **Draft** -- Generate initial code or response
+2. **Plan** -- Self-generate verification questions ("What could be wrong?")
+3. **Execute** -- Answer each question INDEPENDENTLY with no access to the original response
+4. **Revise** -- Incorporate corrections into the final output
+
+```
+Draft --> Plan verification questions --> Execute each independently --> Revise
+```
+
+The critical detail is step 3: each verification runs in isolation. The verifier sees only the verification question and minimal context, not the original draft. This prevents the model from rationalizing its initial mistakes.
+
+### Integration with Blind Review
+
+CoVe operates as a self-correction step BEFORE the blind review system:
+
+```
+Developer Code --> CoVe (self-verification) --> Blind Review (3 parallel reviewers)
+```
+
+CoVe catches errors early via factored checking. Blind review catches remaining issues independently.
+
+## Specialist Review Pool
+
+The 5-specialist pool (detailed in `skills/quality-gates.md`) uses trigger-keyword matching to select the most relevant reviewers:
+
+| Specialist | Trigger Keywords |
+|-----------|-----------------|
+| security-sentinel | auth, login, password, token, api, sql, query, cookie, cors, csrf |
+| performance-oracle | database, query, cache, render, loop, fetch, load, index, join, pool |
+| architecture-strategist | (always included) |
+| test-coverage-auditor | test, spec, coverage, assert, mock, fixture, expect, describe |
+| dependency-analyst | package, import, require, dependency, npm, pip, yarn, lock |
+
+**Selection rules:**
+1. architecture-strategist fills slot 1 (always)
+2. Score remaining 4 specialists by counting keyword matches in the diff
+3. Top 2 fill the remaining slots
+4. Tie-breaker priority: security-sentinel > test-coverage-auditor > performance-oracle > dependency-analyst
+
+## Two-Stage Review Protocol
+
+Code review is split into two distinct stages. Mixing them causes "technically correct but wrong feature" problems.
+
+**Stage 1: Spec Compliance** -- "Does this code implement what the spec requires?"
+- 1 reviewer (spec compliance is objective)
+- Must pass before proceeding to Stage 2
+
+**Stage 2: Code Quality** -- "Is this code well-written, maintainable, secure?"
+- 3 reviewers (blind, parallel)
+- Anti-sycophancy check on unanimous approval
+
+If Stage 1 fails, return to implementation. Do NOT proceed to Stage 2 (reviewing quality of wrong code wastes resources).
+
+## Compound Learning (v5.30.0)
+
+The compound learning system extracts reusable knowledge from completed tasks. It has two phases:
+
+**Deepen-Plan Phase:** Before implementation begins, 4 parallel research agents enhance the plan:
+- Technical feasibility researcher
+- Similar project pattern finder
+- Risk assessment analyst
+- Dependency compatibility checker
+
+**Knowledge Extraction Phase:** After verification passes, if a task produced a novel insight (bug fix, non-obvious solution, reusable pattern), it is extracted to `~/.loki/solutions/{category}/{slug}.md` with YAML frontmatter:
+
+```yaml
+---
+title: Fix bcrypt timing attack in login endpoint
+tags: [security, auth, bcrypt, timing]
+symptoms: Login endpoint vulnerable to timing analysis
+root_cause: Using string comparison instead of constant-time comparison
+prevention: Always use crypto.timingSafeEqual for secret comparison
+---
+```
+
+CLI commands for compound learning:
+
+```bash
+loki compound list      # List extracted solutions
+loki compound show      # Show a specific solution
+loki compound search    # Search solutions by keyword
+loki compound run       # Run extraction on recent tasks
+loki compound stats     # Show extraction statistics
+```
+
+## Event-Driven Hooks
+
+The hooks system (documented in `skills/testing.md`) triggers quality checks on file operations:
+
+```yaml
+triggers:
+  on_file_write:
+    - lint: "npx eslint --fix {file}"
+    - typecheck: "npx tsc --noEmit"
+    - secrets_scan: "detect-secrets scan {file}"
+  on_task_complete:
+    - contract_test: "npm run test:contract"
+    - spec_lint: "spectral lint .loki/specs/openapi.yaml"
+  on_phase_complete:
+    - memory_consolidate: "Extract patterns to semantic memory"
+    - metrics_update: "Log efficiency scores"
+    - checkpoint: "git commit with phase summary"
+```
+
+This catches issues 5-10x earlier than waiting for phase-end review.
+
+## Agent Handoffs
+
+When one agent completes work and another needs to continue, structured handoff data is passed:
+
+```python
+handoff_data = {
+    "completed_work": "Implemented user registration endpoint",
+    "files_modified": ["src/routes/users.ts", "tests/users.test.ts"],
+    "decisions_made": ["Used bcrypt, not argon2", "Email validation via regex"],
+    "open_questions": ["Rate limiting not implemented yet"],
+    "mistakes_learned": ["First attempt had SQL injection - fixed"]
+}
+
+Task(
+    subagent_type="general-purpose",
+    model="sonnet",
+    description="Integration testing for user registration",
+    prompt=f"Previous agent completed: {handoff_data}. Now write integration tests..."
+)
+```
+
+Handoff messages follow the A2A-inspired format and are stored in `.loki/messages/`.
+
+## Summary
+
+Advanced patterns in Loki Mode include structured prompting (GOAL/CONSTRAINTS/CONTEXT/OUTPUT), confidence-based routing for oversight calibration, Chain-of-Verification for self-correction, keyword-triggered specialist review selection, two-stage review separation, compound learning for knowledge extraction, and event-driven hooks for early issue detection. These patterns are documented in `skills/agents.md`, `skills/quality-gates.md`, `skills/testing.md`, and `skills/compound-learning.md`.

package/docs/certification/03-advanced-patterns/quiz.md

@@ -0,0 +1,93 @@
+# Module 3 Quiz: Advanced Patterns
+
+Answer each question by selecting the best option (A, B, C, or D).
+
+---
+
+**Question 1:** What are the four required sections in a structured agent prompt?
+
+A) Task, Input, Process, Output
+B) Goal, Constraints, Context, Output
+C) Objective, Scope, Resources, Deliverables
+D) Summary, Details, Requirements, Acceptance
+
+---
+
+**Question 2:** In confidence-based routing, what happens when a task's confidence score is below 0.40?
+
+A) The task is executed with the cheapest model
+B) The task is automatically retried 3 times
+C) The task is flagged for human decision
+D) The task is split into smaller subtasks
+
+---
+
+**Question 3:** What is the critical feature of Step 3 (Execute) in the Chain-of-Verification process?
+
+A) All verifications run sequentially in the same context
+B) The verifier has full access to the original response for comparison
+C) Each verification runs independently with NO access to the original response
+D) A human must approve each verification question
+
+---
+
+**Question 4:** In the specialist review pool, what is the tie-breaker priority order?
+
+A) performance-oracle > dependency-analyst > security-sentinel > test-coverage-auditor
+B) security-sentinel > test-coverage-auditor > performance-oracle > dependency-analyst
+C) test-coverage-auditor > security-sentinel > dependency-analyst > performance-oracle
+D) dependency-analyst > performance-oracle > test-coverage-auditor > security-sentinel
+
+---
+
+**Question 5:** Why is code review split into two stages (spec compliance and code quality)?
+
+A) To reduce the number of reviewers needed
+B) To prevent approving well-written code that implements the wrong feature
+C) To allow junior developers to handle Stage 1
+D) To make the review process faster
+
+---
+
+**Question 6:** What triggers the compound learning knowledge extraction phase?
+
+A) Every task completion regardless of outcome
+B) Only when a task produces a novel insight (bug fix, non-obvious solution, reusable pattern)
+C) Only when the project reaches the DEPLOYMENT phase
+D) Only when manually invoked with `loki compound run`
+
+---
+
+**Question 7:** Which agent is ALWAYS included in the deepen-plan research phase?
+
+A) There are no fixed agents; all 4 are selected dynamically
+B) The security risk assessor
+C) All 4 research agents always run in parallel
+D) Only the technical feasibility researcher
+
+---
+
+**Question 8:** What is the purpose of the `on_file_write` hook trigger?
+
+A) To back up files before they are modified
+B) To run lint, typecheck, and secrets scanning immediately after a file is written
+C) To log all file changes to the audit trail
+D) To prevent agents from writing to protected files
+
+---
+
+**Question 9:** In the two-stage review protocol, what happens if Stage 1 (spec compliance) fails?
+
+A) The code goes directly to Stage 2 for quality feedback
+B) The review is cancelled and a new agent is assigned
+C) The code returns to implementation; Stage 2 is NOT started
+D) Both stages run in parallel anyway to save time
+
+---
+
+**Question 10:** What information is included in a structured agent handoff?
+
+A) Only the list of files modified
+B) Completed work, files modified, decisions made, open questions, and mistakes learned
+C) Only the task ID and completion status
+D) A full copy of the agent's conversation history

package/docs/certification/04-production-deployment/lab.md

@@ -0,0 +1,160 @@
+# Module 4 Lab: Deploy with Docker Compose
+
+## Objective
+
+Deploy Loki Mode using Docker Compose, verify the dashboard is accessible, and configure resource limits.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- Loki Mode source or repository cloned
+- An AI provider API key (e.g., `ANTHROPIC_API_KEY` for Claude)
+
+## Step 1: Review the Docker Compose Configuration
+
+Examine the `docker-compose.yml` at the repository root:
+
+```bash
+cat docker-compose.yml
+```
+
+Key elements to note:
+- The service mounts your current directory as `/workspace` (read-write)
+- Git config and SSH keys are mounted read-only
+- The dashboard port 57374 is exposed
+- GitHub token is passed through from the host environment
+
+## Step 2: Build the Docker Image
+
+```bash
+docker-compose build
+```
+
+This builds from the `Dockerfile` which installs:
+- Ubuntu 24.04 base
+- Node.js 20 LTS
+- Python 3 with venv support
+- Git, jq, GitHub CLI
+- Loki Mode and its dependencies
+
+## Step 3: Start with Docker Compose
+
+Create a test project directory and start Loki Mode:
+
+```bash
+mkdir -p /tmp/docker-lab && cd /tmp/docker-lab
+git init
+
+# Create a minimal PRD
+cat > prd.md << 'EOF'
+# Hello World API
+
+## Overview
+A simple Express.js REST API that returns "Hello, World!" on GET /.
+
+## Requirements
+- GET / returns JSON: {"message": "Hello, World!"}
+- Responds with HTTP 200
+- Unit test verifies the response
+
+## Tech Stack
+- Node.js with Express
+EOF
+```
+
+Start the container (this will invoke the AI provider and may incur costs):
+
+```bash
+# Pass your API key through to the container
+ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY docker-compose run \
+  -e ANTHROPIC_API_KEY \
+  loki start ./prd.md
+```
+
+**Note:** Replace `ANTHROPIC_API_KEY` with the appropriate key for your provider (`OPENAI_API_KEY` for Codex, `GOOGLE_API_KEY` for Gemini).
+
+## Step 4: Verify the Dashboard
+
+While the container is running, access the dashboard from your host browser:
+
+```bash
+# The dashboard should be available at:
+open http://localhost:57374
+```
+
+If using the API:
+
+```bash
+curl http://localhost:57374/api/health
+```
+
+## Step 5: Configure Resource Limits
+
+Test resource configuration by modifying environment variables:
+
+```bash
+# Run with budget limit and reduced parallel agents
+docker-compose run \
+  -e ANTHROPIC_API_KEY \
+  -e LOKI_BUDGET_LIMIT=5.00 \
+  -e LOKI_MAX_PARALLEL_AGENTS=3 \
+  -e LOKI_MAX_ITERATIONS=50 \
+  loki start --simple ./prd.md
+```
+
+## Step 6: Use the Sandbox Mode
+
+Test the sandbox mode which provides additional isolation:
+
+```bash
+# Build the sandbox image
+loki sandbox build
+
+# Start the sandbox
+loki sandbox start
+
+# Check status
+loki sandbox status
+
+# Open a shell inside the sandbox
+loki sandbox shell
+
+# View logs
+loki sandbox logs
+
+# Stop the sandbox
+loki sandbox stop
+```
+
+## Step 7: Verify Health Monitoring
+
+Check process and system health:
+
+```bash
+# From inside the container or on the host with loki installed:
+loki watchdog status
+loki secrets status
+```
+
+## Verification Checklist
+
+- [ ] `docker-compose build` completes without errors
+- [ ] `docker-compose run loki version` outputs the correct version
+- [ ] The dashboard is accessible at `http://localhost:57374`
+- [ ] You can pass environment variables to configure resource limits
+- [ ] `loki sandbox` commands work (build, start, status, stop)
+- [ ] You understand the volume mounts and their permissions (rw vs ro)
+
+## Cleanup
+
+```bash
+# Stop any running containers
+docker-compose down
+
+# Remove test directory
+cd ~
+rm -rf /tmp/docker-lab
+
+# Optional: remove the Docker image
+docker rmi loki-mode:latest
+```

package/docs/certification/04-production-deployment/lesson.md

@@ -0,0 +1,261 @@
+# Module 4: Production Deployment
+
+## Overview
+
+Loki Mode can be deployed using Docker, Docker Compose, or direct installation via npm/Homebrew. This module covers deployment options, security hardening, resource management, and production configuration.
+
+## Installation Methods
+
+### npm (Recommended for Development)
+
+```bash
+npm install -g loki-mode
+loki version
+loki doctor
+```
+
+### Docker
+
+The Docker image is based on Ubuntu 24.04 and includes Node.js 20 LTS, Python 3, Git, jq, and the GitHub CLI.
+
+```bash
+# Pull the image
+docker pull asklokesh/loki-mode:5.52.0
+
+# Run interactively with workspace mounted
+docker run -it -v $(pwd):/workspace asklokesh/loki-mode:latest
+```
+
+The Dockerfile is at the repository root (`Dockerfile`). A separate `Dockerfile.sandbox` exists for sandboxed execution.
+
+### Docker Compose
+
+The `docker-compose.yml` at the repository root provides a ready-to-use configuration:
+
+```yaml
+services:
+  loki:
+    build: .
+    image: loki-mode:latest
+    volumes:
+      - .:/workspace:rw
+      - ~/.gitconfig:/home/loki/.gitconfig:ro
+      - ~/.ssh:/home/loki/.ssh:ro
+      - ~/.config/gh:/home/loki/.config/gh:ro
+    environment:
+      - LOKI_DASHBOARD=true
+      - LOKI_DASHBOARD_PORT=57374
+      - GITHUB_TOKEN
+      - GH_TOKEN
+    ports:
+      - "57374:57374"
+    working_dir: /workspace
+    stdin_open: true
+    tty: true
+```
+
+Start with:
+
+```bash
+docker-compose run loki start ./prd.md
+```
+
+Key volume mounts:
+- `.:/workspace:rw` -- Your project directory (read-write)
+- `~/.gitconfig:/home/loki/.gitconfig:ro` -- Git configuration (read-only)
+- `~/.ssh:/home/loki/.ssh:ro` -- SSH keys for git operations (read-only)
+- `~/.config/gh:/home/loki/.config/gh:ro` -- GitHub CLI authentication (read-only)
+
+### Docker Sandbox
+
+For isolated execution with additional security:
+
+```bash
+loki sandbox start     # Start sandbox container
+loki sandbox status    # Check status
+loki sandbox shell     # Open interactive shell
+loki sandbox logs      # View container logs
+loki sandbox stop      # Stop container
+```
+
+Or pass `--sandbox` to the start command:
+
+```bash
+loki start --sandbox ./prd.md
+```
+
+The sandbox uses `Dockerfile.sandbox` which adds additional isolation constraints.
+
+## Security Hardening
+
+### TLS for Dashboard
+
+Enable HTTPS for the dashboard API:
+
+```bash
+export LOKI_TLS_CERT=/path/to/fullchain.pem
+export LOKI_TLS_KEY=/path/to/privkey.pem
+loki dashboard start
+```
+
+### Path Restrictions
+
+Limit which directories agents can modify:
+
+```bash
+export LOKI_ALLOWED_PATHS=/workspace/src,/workspace/tests
+```
+
+Agents will only be able to write to the specified directories.
+
+### Command Blocking
+
+Block dangerous shell commands:
+
+```bash
+export LOKI_BLOCKED_COMMANDS="rm -rf /,dd if=/dev/zero"
+```
+
+### Agent Limits
+
+Control concurrent agent spawning:
+
+```bash
+export LOKI_MAX_PARALLEL_AGENTS=5    # Default: 10
+```
+
+### Staged Autonomy
+
+Require human approval before execution:
+
+```bash
+export LOKI_STAGED_AUTONOMY=true
+```
+
+### OIDC Authentication
+
+For SSO integration:
+
+```bash
+export LOKI_OIDC_ISSUER=https://accounts.google.com
+export LOKI_OIDC_CLIENT_ID=your-client-id
+export LOKI_OIDC_AUDIENCE=your-audience
+```
+
+## Resource Management
+
+### Budget Limits
+
+Set a cost budget to auto-pause when exceeded:
+
+```bash
+loki start --budget 10.00 ./prd.md
+# Or via environment variable:
+export LOKI_BUDGET_LIMIT=10.00
+```
+
+### Resource Monitoring
+
+Loki Mode monitors system resources during execution:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_RESOURCE_CHECK_INTERVAL` | `300` | Check resources every N seconds |
+| `LOKI_RESOURCE_CPU_THRESHOLD` | `80` | CPU % threshold to warn |
+| `LOKI_RESOURCE_MEM_THRESHOLD` | `80` | Memory % threshold to warn |
+
+### Iteration Limits
+
+Control how many iterations the agent loop runs:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_MAX_ITERATIONS` | `1000` | Max loop iterations before exit |
+| `LOKI_MAX_RETRIES` | `50` | Max retry attempts on failure |
+| `LOKI_PERPETUAL_MODE` | `false` | Ignore all completion signals |
+
+### Parallel Execution
+
+For parallel mode with git worktrees (Claude only):
+
+```bash
+loki start --parallel ./prd.md
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_PARALLEL_MODE` | `false` | Enable worktree-based parallelism |
+| `LOKI_MAX_WORKTREES` | `5` | Maximum parallel worktrees |
+| `LOKI_MAX_PARALLEL_SESSIONS` | `3` | Maximum concurrent AI sessions |
+
+## Completion Council
+
+The completion council prevents premature termination and infinite loops. It is a group of agents that vote on whether the project is truly complete.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_COUNCIL_ENABLED` | `true` | Enable completion council |
+| `LOKI_COUNCIL_SIZE` | `3` | Number of council members |
+| `LOKI_COUNCIL_THRESHOLD` | `2` | Votes needed for completion |
+| `LOKI_COUNCIL_CHECK_INTERVAL` | `5` | Check every N iterations |
+| `LOKI_COUNCIL_MIN_ITERATIONS` | `3` | Min iterations before council runs |
+| `LOKI_COUNCIL_STAGNATION_LIMIT` | `5` | Max iterations with no git changes |
+
+CLI commands:
+
+```bash
+loki council status        # Check council state
+loki council verdicts      # View past verdicts
+loki council convergence   # Check convergence metrics
+loki council force-review  # Force a council review
+loki council report        # Generate council report
+```
+
+## QA Phase Configuration
+
+Individual QA sub-phases can be enabled or disabled:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_PHASE_UNIT_TESTS` | `true` | Run unit tests |
+| `LOKI_PHASE_API_TESTS` | `true` | Functional API testing |
+| `LOKI_PHASE_E2E_TESTS` | `true` | E2E/UI testing with Playwright |
+| `LOKI_PHASE_SECURITY` | `true` | Security scanning (OWASP/auth) |
+| `LOKI_PHASE_CODE_REVIEW` | `true` | 3-reviewer parallel code review |
+| `LOKI_PHASE_PERFORMANCE` | `true` | Load/performance testing |
+| `LOKI_PHASE_ACCESSIBILITY` | `true` | WCAG compliance testing |
+| `LOKI_PHASE_REGRESSION` | `true` | Regression testing |
+
+## Health Monitoring
+
+### Dashboard Health
+
+The dashboard API server exposes a health endpoint. When running:
+
+```bash
+loki dashboard status
+# Or via API:
+curl http://localhost:57374/api/health
+```
+
+### Process Watchdog
+
+Monitor Loki Mode process health:
+
+```bash
+loki watchdog status    # Check process health
+loki watchdog help      # Show watchdog commands
+```
+
+### Secrets Validation
+
+Validate that API keys are properly configured:
+
+```bash
+loki secrets status     # Check API key status
+loki secrets validate   # Validate keys are functional
+```
+
+## Summary
+
+Loki Mode supports Docker, Docker Compose, and npm deployment. Security hardening includes TLS, path restrictions, command blocking, OIDC, and staged autonomy. Resource management covers budget limits, CPU/memory thresholds, iteration limits, and parallel execution constraints. The completion council prevents premature termination. All configuration is done through environment variables, making it compatible with any deployment system.