loki-mode 11.3.0 → 11.3.1

package/docs/KNOWN-ISSUES.md

@@ -1,41 +1,17 @@
+# Known issues
 
-## doctor --json writes 108 bytes to stderr on a provider-less host
+Issues in the current release that are known and not yet fixed. Report new ones with `loki crash` or at https://github.com/asklokesh/loki-mode/issues.
 
-`bash autonomy/loki doctor --json` on a host with NO provider CLI emits:
+## `loki verify` exit codes differ from the target table in three cases
 
-```
-autonomy/loki: line 14066: required: command not found
-autonomy/loki: line 14066: status: command not found
-```
+| Input | Command | Exit today | Target |
+|---|---|---|---|
+| Empty diff (a git repo with no changes vs base) | `loki verify` | 1 (CONCERNS) | 3 |
+| Not a git directory | `loki verify` | 1 (CONCERNS) | 2 |
+| Unknown flag | `loki verify` with a flag it does not know | 3 | 64 |
 
-**Not user-affecting, and not a JSON defect.** stdout is 5176 bytes of valid
-JSON; only stderr is polluted. Every `doctor --json` assertion in the repo
-discards stderr (`tests/test-airgap-commands.sh:50`,
-`tests/test-doctor-ci-gateable.sh:46,84,86`).
-`tests/test-e2e-features.sh:104` was the lone outlier using `2>&1` and has been
-brought into line.
+Changing these is a breaking change for CI gates, so it waits for a planned release. Details: [exit-codes.md](exit-codes.md#known-gaps).
 
-**Attribution:** introduced this session. `git show 0416810d:autonomy/loki`
-(v9.48.2) emits 0 bytes on the same host; HEAD emits 108. The region was last
-touched by `56e03374 feat(doctor): show provider availability`.
-
-**Six hypotheses tested and REFUTED, so the next person does not repeat them:**
-
-1. Word-splitting of `$_provider_availability` at `:14066` -- the assignment is
-   correctly quoted; reproduced in isolation as OK.
-2. `provider_availability_json` emitting to stderr -- 0 bytes, clean 353-byte
-   JSON in isolation.
-3. Its callees `auto_detect_provider` / `check_provider_installed` -- both
-   silent.
-4. The JSON value's content -- `required` and `status` appear 0 times in it.
-5. The value being multi-line and breaking the env-assignment chain -- forcing
-   `LOKI_PROVIDER_AVAILABILITY=""` as a literal STILL reproduces.
-6. `render_provider_availability` -- silent in isolation, and disabling the call
-   still reproduces.
-
-**Also known:** `bash -n` parses the file clean; sourcing the file and calling
-`cmd_doctor_json` directly emits 0 bytes, while executing the file emits 108.
-That difference (streaming read vs single parse) is the strongest remaining
-lead. The words `required` and `status` are python identifiers at `:14085-14098`
-inside the `python3 -c "` string that opens at `:14069`.
+## `loki start` uses the older engine
 
+`loki "<task>"`, `loki owner/repo#N` and `loki quick` run the Loki 10 engine. `loki start ./prd.md` still routes to the older engine, which is being removed. Prefer `loki owner/repo#N` or `loki "<task>"`.

package/docs/TESTING.md

@@ -0,0 +1,161 @@
+# Testing
+
+This document describes the test strategy, test types, and how to run and configure tests for Loki Mode.
+
+Loki Mode is a polyglot codebase. Tests span three languages and runtimes:
+
+- Bash (orchestration engine, CLI, councils, hooks)
+- Python (dashboard API, memory system, benchmarks, MCP server)
+- TypeScript / JavaScript (the Bun runner under `loki-ts/`, the Deno/Node API under `api/`, dashboard UI checks)
+
+Because the product's central promise is verified completion ("Loki does not lie about done"), the test suite is treated as a trust layer, not a formality. Trust-surface code (completion councils, quality gates, evidence receipts, the Bun runner, memory integrity) is held to a higher bar: mutation testing, parity checks, and adversarial detectors back the standard unit and integration tests.
+
+## Test Strategy
+
+1. Test the trust surface hardest. Completion detection, override councils, the verified-completion evidence gate, and the RARV-C closure loop are the highest-risk paths. They get unit tests plus mutation testing plus cross-route parity checks.
+2. Cross-route parity is a first-class concern. Behavior must match between the legacy Bash route and the Bun (`loki-ts`) route. Parity is checked by `tests/test-bash-bun-parity.sh` and the per-command parity suites under `tests/` (for example, doctor-output text drift); there is no continuous parity workflow.
+3. Prefer real verification over mocked assertions. Dedicated detectors (`tests/detect-mock-problems.sh`, `tests/detect-semantic-test-problems.sh`, `tests/detect-test-mutations.sh`, `tests/detect-invariant-violations.sh`) flag tests that pass without exercising real logic.
+4. Local CI is the canonical pre-push gate. `scripts/local-ci.sh` mirrors the GitHub Actions workflows so failures are discovered on the developer machine, not after push. GitHub Actions is the post-push verifier.
+5. Run tests in matrices. Python runs across 3.10 through 3.13; the Node suite runs across the supported Node versions. Version-specific breakage (for example, a Python 3.13-only inode race) must be caught by the matrix.
+
+## Test Types
+
+### Unit tests
+
+- Bash unit tests live under `tests/` (for example `tests/cli/`, `tests/council/`, `tests/memory/`) and are orchestrated by `tests/run-all-tests.sh`. They cover bootstrap, task queue, circuit breaker, agent timeout, state recovery, and the memory engine, among others. Several use function extraction: a helper is sourced out of `run.sh` and exercised in isolation. When a helper gains a new dependency, the extraction test must extract that dependency too, or the logic is silently skipped.
+- Python unit tests are `tests/test_*.py` files (120+ modules) covering the classifier, composer, calibration, embeddings edge cases, event bus, compose port selection, app-runner PID recycling, and more. They run under `pytest`.
+- TypeScript unit tests live under `loki-ts/tests/` (70+ `*.test.ts` files) and run under `bun test`. They cover the runner internals: state, prompt building, providers, budget, checkpoint, and shell utilities.
+- Node/Deno unit tests are `*_test.ts` and `*.test.js` files under `api/` and `tests/` (protocols, observability, policies, audit, integrations), run with `node --test`.
+
+### Integration tests
+
+- `tests/integration/` holds the integration suite, run via `bash tests/integration/run_integration_suite.sh` (also exposed as `npm run test:integration`).
+- `tests/integrations/` covers external system integrations (GitHub, Jira, Slack), run with `node --test`.
+- Managed-memory integration is gated behind flags and covered by `tests/managed_memory/` (flag matrix, SDK isolation, kill switch, shadow-write, retrieve).
+
+### End-to-end tests
+
+- `tests/e2e/` and `tests/live/` contain end-to-end and live-path scenarios.
+- Control Plane UI E2E lives in `packages/control-plane/test/e2e/` (Playwright, headless, loopback stub API).
+- Docker E2E lives under `tests/docker/` with the `docker/Dockerfile.sandbox` image.
+- Post-release distribution E2E is run after a release ships: install from the npm tarball, pull the Docker image, and exercise both the Bun and legacy-Bash routes on each channel.
+
+### Specialized test layers
+
+- Mutation testing (`loki-ts`): Stryker mutates trust-surface modules (`src/runner/state.ts`, `build_prompt.ts`, `providers.ts`, `budget.ts`, `checkpoint.ts`, `src/util/shell.ts`). Config: `loki-ts/stryker.config.json`. Thresholds: break 50%, low 60%, high 80%.
+- Parity tests: `tests/test-bash-bun-parity.sh` and the per-command parity suites verify the Bun and Bash routes agree.
+- Integrity and quality detectors: shell scripts under `tests/` that detect mock-only tests, semantic test problems, test mutations, and invariant violations.
+
+## How to Run Tests
+
+### Quick start
+
+```bash
+# Full default suite (bash syntax checks + node --test suites + managed-memory)
+npm test
+
+# Pre-push gate: mirrors every CI workflow. Run this before every git push.
+bash scripts/local-ci.sh
+```
+
+If `local-ci.sh` reports "DO NOT PUSH", do not push. Fix the failures and re-run.
+
+### By language and layer
+
+```bash
+# Bash shell test suite
+bash tests/run-all-tests.sh
+
+# Python tests (all)
+python3 -m pytest
+
+# Python tests (single module)
+python3 -m pytest tests/test_classifier.py -v
+
+# TypeScript / Bun runner tests
+cd loki-ts && bun test
+
+# Bun runner type check
+cd loki-ts && bun run typecheck
+
+# Integration suite
+npm run test:integration
+# or
+bash tests/integration/run_integration_suite.sh
+
+# Control Plane tests
+cd packages/control-plane && bun test ./test/
+```
+
+### Mutation testing (local)
+
+```bash
+cd loki-ts && npx stryker run
+```
+
+### Syntax-only validation (fast smoke)
+
+```bash
+bash -n autonomy/run.sh
+bash -n autonomy/loki
+bash -n autonomy/completion-council.sh
+python3 -c "import ast, os; [ast.parse(open(f'dashboard/{f}').read()) for f in os.listdir('dashboard') if f.endswith('.py')]"
+```
+
+### Cleanup after test runs (mandatory)
+
+Spawned processes and temp files must be cleaned up after any run that starts a server or test runner:
+
+```bash
+lsof -ti:57374 | xargs kill -9 2>/dev/null || true
+pkill -f "loki-run-" 2>/dev/null || true
+rm -rf /tmp/loki-* /tmp/test-* /tmp/package /tmp/*.tgz 2>/dev/null || true
+
+# Verify
+ps -ef | grep -E "(loki|test)" | grep -v grep || echo "Clean"
+```
+
+Note: never run `rm -rf /tmp/loki-*` while a live `loki` run is in progress; the orchestrator stages its run script at `/tmp/loki-run-*.sh`. Check `pgrep -f loki-run-` first.
+
+## Test Configuration
+
+| Area | Tool | Config / entry point |
+|---|---|---|
+| Default test command | mixed (bash, node) | `package.json` `test` script |
+| Bash suite | bash | `tests/run-all-tests.sh` |
+| Python | pytest | invoked via `python3 -m pytest`; deps: `pytest`, `pytest-asyncio` |
+| Bun runner | bun test | `loki-ts/package.json`, `loki-ts/bunfig.toml` |
+| Node/Deno | `node --test` | `*_test.ts`, `*.test.js` |
+| Mutation | Stryker | `loki-ts/stryker.config.json` |
+| Control Plane UI E2E | Playwright | `packages/control-plane/test/e2e/` |
+| Pre-push gate | bash | `scripts/local-ci.sh` |
+
+Python test dependencies commonly required: `fastapi`, `httpx`, `pydantic`, `sqlalchemy[asyncio]`, `aiosqlite`, `uvicorn`. Install with pip before running the Python suite.
+
+## Coverage Goals
+
+- No CI workflow collects or enforces a numeric line-coverage percentage. `bun test --coverage` can be run locally in `loki-ts`.
+- Mutation-score thresholds for trust-surface modules: break at 50%, low at 60%, high at 80% (`loki-ts/stryker.config.json`).
+- The Bash, Python and Bun suites do not currently enforce a numeric coverage percentage. Coverage of trust-surface logic is asserted through targeted unit tests, parity checks, and the mock/semantic/mutation detectors rather than a global percentage.
+
+## CI Integration
+
+GitHub Actions workflows (under `.github/workflows/`) run on push and pull request:
+
+| Workflow | File | What it runs |
+|---|---|---|
+| Tests | `test.yml` | Node suite (`npm test`), Python suite (`pytest`) across 3.10-3.13, shell suite (`tests/run-all-tests.sh`), Helm lint |
+| Integrity audit | `integrity-audit.yml` | Repository and artifact integrity checks |
+| Post-release smoke | `post-release-smoke.yml` | Smoke tests against published artifacts after a release |
+| Security audit | `security-audit.yml` | Dependency and security scanning |
+| SBOM | `sbom.yml` | Software bill of materials generation |
+
+### Local CI mirrors GitHub Actions
+
+`scripts/local-ci.sh` is the canonical pre-push gate. It mirrors every GitHub Actions workflow: bun typecheck/test, the full `tests/run-all-tests.sh` shell suite (matching CI exactly, not a cherry-picked subset), npm pack contents, SBOM, license audit, npm audit, shellcheck, YAML parse, the no-emoji check, the no-`git add -A` check, and a cleanup probe.
+
+Run it before every push. The Mac (developer machine) is the discovery channel; GitHub Actions is the post-push verifier. Distinguish real failures from local-environment false alarms (for example a missing `pytest-asyncio` in a Homebrew Python) before acting on a red result.
+
+### Release-time validation
+
+Before a release is committed, the npm tarball is verified to contain the built dashboard and web-app artifacts, and a fresh global install is exercised end to end (`loki --version`, `loki web`, `/api/status`). After a release ships, post-release distribution validation runs across npm, Docker, and Homebrew on both the Bun and legacy-Bash routes.

package/docs/air-gapped.md

@@ -90,8 +90,7 @@ your network, but the audit still counts it as required egress.
 Telemetry is ON by default for an individual interactive install and auto-off
 in CI, non-interactive, `LOKI_ENTERPRISE=true` and `LOKI_AIRGAP=true`
 contexts. The audit shows its real state. Every opt-out wins (`DO_NOT_TRACK=1`,
-`LOKI_TELEMETRY=off`, `loki telemetry off`). The adoption instrumentation added
-in v8.6.0 requires a second explicit opt-in on top of that -- see
+`LOKI_TELEMETRY=off`, `loki telemetry off`). The adoption instrumentation requires a second explicit opt-in on top of that -- see
 [PRIVACY.md](./PRIVACY.md).
 
 ## Why `unknown` is the right answer offline

package/docs/alternative-installations.md

@@ -1,6 +1,6 @@
 # Alternative Installation Methods
 
-The recommended installation is via npm or Homebrew (see [README](../README.md#get-started-in-30-seconds)). These alternatives serve specific use cases.
+The recommended installation is via npm or Homebrew (see [INSTALLATION.md](INSTALLATION.md)). These alternatives serve specific use cases.
 
 ---
 
@@ -16,7 +16,7 @@ git clone https://github.com/asklokesh/loki-mode.git ~/.claude/skills/loki-mode
 ln -sf ~/.claude/skills/loki-mode ~/.codex/skills/loki-mode
 
 # Optionally add CLI to PATH:
-ln -sf ~/.claude/skills/loki-mode/autonomy/loki /usr/local/bin/loki
+ln -sf ~/.claude/skills/loki-mode/bin/loki /usr/local/bin/loki
 ```
 
 **Update:** `cd ~/.claude/skills/loki-mode && git pull`
@@ -27,21 +27,21 @@ ln -sf ~/.claude/skills/loki-mode/autonomy/loki /usr/local/bin/loki
 
 ## Docker
 
-**Status:** Image exists on Docker Hub. Tags: `latest`, version-specific (e.g., `9.8.0`).
+**Status:** Image exists on Docker Hub. Tags: `latest`, one per release version (for example `X.Y.Z`, matching the npm version).
 
 ```bash
 docker pull asklokesh/loki-mode:latest
 ```
 
-**Limitation:** Claude Code is an interactive CLI that requires API keys and terminal access. Running it inside a Docker container is not the standard workflow. Docker is useful for:
+**Limitation:** The image ships the Claude Code CLI. Docker is useful for:
 
 - CI/CD sandbox execution (running `loki` in isolated environments)
 - Testing Loki Mode without modifying your local system
 - Air-gapped environments with pre-built images
 
-**Not recommended for:** Interactive Claude Code sessions. Use npm or Homebrew instead.
+`loki docker <command>` runs any loki command in the image with the current folder mounted, so `.loki/` state and resume behave like the local CLI.
 
-See [DOCKER_README.md](../DOCKER_README.md) for Docker-specific usage instructions.
+See [DOCKER.md](DOCKER.md) for Docker-specific usage instructions.
 
 ---
 
@@ -63,7 +63,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: asklokesh/loki-mode@v8.0.0
+      - uses: asklokesh/loki-mode@vX.Y.Z   # pin a release tag
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           mode: review
@@ -75,7 +75,7 @@ jobs:
 ```
 
 **Prerequisites:**
-- API key for your provider (set as repository secret): `ANTHROPIC_API_KEY` (Claude, recommended) or `OPENAI_API_KEY` (Codex). `GOOGLE_API_KEY` was for the Gemini provider, which is DEPRECATED as of v7.5.18.
+- API key for your provider (set as repository secret): `ANTHROPIC_API_KEY` (Claude, recommended) or `OPENAI_API_KEY` (Codex).
 - The action auto-installs `loki-mode` and `@anthropic-ai/claude-code`
 
 **Action Inputs:**
@@ -83,13 +83,13 @@ jobs:
 | Input | Default | Description |
 |-------|---------|-------------|
 | `mode` | `review` | `review`, `fix`, or `test` |
-| `provider` | `claude` | `claude` (recommended), `cline`, `codex`, `aider`, or `opencode`. `gemini` was REMOVED in v7.5.18. |
+| `provider` | `claude` | `claude` (recommended), `cline`, `codex`, `aider`, or `opencode`. |
 | `budget_limit` | `5.00` | Max cost in USD (passed to the Loki 10 engine as `--max-cost`) |
 | `max_iterations` | `3` | Max RARV cycles |
 | `github_token` | (required) | GitHub token for PR comments |
 | `prd_file` | | Path to PRD file (for fix/test modes) |
 
-**Engine:** every mode runs the Loki 10 engine through `loki start "<task>" --no-pr --provider <name> --max-cost <usd>` (the same path as `loki start owner/repo#N`). The PRD file or PR diff is folded into the task text. The action never opens a PR itself (Rule of Two). A run that crosses the cap ends BUDGET_STOP (exit 3). The legacy `--simple` path is no longer used.
+**Engine:** every mode runs the Loki 10 engine through `loki start "<task>" --no-pr --provider <name> --max-cost <usd>` (the same path as `loki start owner/repo#N`). The PRD file or PR diff is folded into the task text. The action never opens a PR itself (Rule of Two). A run that crosses the cap ends BUDGET_STOP (exit 3).
 
 **Modes:**
 
@@ -108,20 +108,10 @@ jobs:
 **Status:** Working. Release assets available for each version.
 
 ```bash
-# Download and extract to skills directory
-curl -sL https://github.com/asklokesh/loki-mode/archive/refs/tags/v8.0.0.tar.gz | tar xz
-mv loki-mode-8.0.0 ~/.claude/skills/loki-mode
+# Download the latest release and extract to the skills directory
+VERSION=$(npm view loki-mode version)
+curl -sL https://github.com/asklokesh/loki-mode/archive/refs/tags/v${VERSION}.tar.gz | tar xz
+mv loki-mode-${VERSION} ~/.claude/skills/loki-mode
 ```
 
 **Best for:** Offline or air-gapped environments, pinned version deployments.
-
----
-
-## VS Code Extension (Deprecated)
-
-> **DEPRECATED as of v7.2.0.** The Loki Mode VS Code extension is no longer
-> maintained and is no longer published to the VS Code Marketplace. Use the
-> Control Plane instead (`loki dashboard`).
-> The `vscode-extension/` source remains in the repository for contributors who
-> want to build it locally. See
-> [INSTALLATION.md](INSTALLATION.md#vs-code-extension-deprecated) for details.

package/docs/architecture/DECISIONS.md

@@ -0,0 +1,333 @@
+# Architectural Decision Records
+
+This document records the significant architectural decisions for **loki-mode**,
+an autonomous spec-to-product system. Each record captures the context in which
+a decision was made, the decision itself, and the consequences that follow.
+
+Decisions are listed newest-first by ADR number. A decision marked **Superseded**
+remains for historical reference; the record that replaces it is named inline.
+
+For the detailed runtime-migration record, see
+`docs/architecture/ADR-001-runtime-migration.md`. The summary below mirrors its
+high-level conclusions.
+
+---
+
+## ADR-001: Migrate the orchestrator runtime from bash to Bun/TypeScript
+
+**Status:** Accepted (phased; bash sunset gated on a clean soak)
+
+### Context
+
+The original orchestrator was implemented as two very large bash programs:
+`autonomy/run.sh` (the RARV-C iteration loop) and `autonomy/loki` (the CLI, with
+100+ command handlers). At over 10,000 lines each they were untyped, fragile,
+and hard to refactor or test. As the product grew, the cost of changing core
+control flow in bash kept rising, and the lack of static typing meant defects
+surfaced only at runtime in users' terminals.
+
+### Decision
+
+Port the orchestrator and CLI to TypeScript running on Bun (`loki-ts/`). Ship the
+migration in phases (scaffold, read-only commands, build tooling, outer loop,
+council and code review, then bash sunset) rather than as a single rewrite. A
+`bin/loki` shim routes ported commands to the Bun CLI and falls through to the
+bash implementation for the rest. `LOKI_LEGACY_BASH=1` forces the bash route as a
+rollback escape hatch.
+
+### Consequences
+
+- Both runtimes coexist during the migration, so every behavior must be verified
+  for cross-route parity. A dedicated parity matrix in CI guards against drift.
+- New work lands in typed TypeScript with `bun test` coverage; the bash code is
+  frozen and only patched for parity.
+- The final phase (deleting `run.sh` and `autonomy/loki`, removing the legacy
+  flag) is deliberately gated behind a multi-week clean soak with zero parity
+  regressions, rather than shipped on a date.
+- Carrying two implementations is real maintenance overhead until sunset, traded
+  for a safe, reversible rollout.
+
+---
+
+## ADR-002: Provider-agnostic execution with automatic failover
+
+**Status:** Accepted
+
+### Context
+
+Tying the system to a single AI vendor would be a hard dependency and a single
+point of failure. Users run different coding agents (Claude Code, OpenAI Codex
+CLI, Cline, Aider) with different capabilities, and the product positioning
+("no vendor lock-in") requires running on more than one.
+
+### Decision
+
+Abstract provider invocation behind shell-sourceable provider configs
+(`providers/*.sh`) and a TypeScript provider layer
+(`loki-ts/src/runner/providers.ts`), classified by capability tier:
+
+- **Claude Code (Tier 1):** full features (subagents, parallelism, Task tool, MCP).
+- **Cline (Tier 2):** reduced parallelism.
+- **OpenAI Codex CLI and Aider (Tier 3):** degraded mode (sequential, no Task tool).
+
+The orchestrator adapts its strategy to the active provider's tier and fails over
+automatically. Google Gemini CLI was deprecated (v7.5.18) after upstream
+deprecation; selecting it exits with a migration message.
+
+### Consequences
+
+- Features must degrade gracefully: anything Tier 1 specific cannot be assumed
+  available, so the loop checks capability before using it.
+- Adding a provider means adding a config plus tier mapping, not rewriting the loop.
+- The capability matrix is a permanent part of the design and must be kept honest;
+  a provider listed at a tier it cannot meet would break runs silently.
+
+---
+
+## ADR-003: Verified completion via the RARV-C closure loop and an Evidence Receipt
+
+**Status:** Accepted
+
+### Context
+
+Most coding agents declare a task "done" by narrating it in a transcript, which
+is unverifiable. The product's core differentiator is trust: "done" must mean
+proven, not promised. An agent that lies about completion (empty diffs, failing
+tests reported green) destroys user confidence and word-of-mouth.
+
+### Decision
+
+Every iteration runs the RARV-C cycle (Reason, Act, Reflect, Verify, Close).
+Completion is decided by deterministic, re-derivable facts rather than the
+agent's own claim:
+
+- An empty git diff against the run-start commit cannot be reported as done.
+- Red tests block completion.
+- Each build produces an **Evidence Receipt** separating **Facts** (diff SHAs,
+  file counts, test command and exit code, build command and exit code, gate
+  verdicts) from **Assessments** (AI judgments such as the review council).
+- The receipt headline (VERIFIED / VERIFIED WITH GAPS / NOT VERIFIED) is computed
+  only from the facts; gaps are always listed by name so silence never reads as a
+  pass.
+
+### Consequences
+
+- Completion logic must stay deterministic and independently re-checkable; LLM
+  judgment can inform but never make the headline green on its own.
+- `loki verify` exposes the same gates as a standalone, CI-ready check with
+  machine-readable evidence and meaningful exit codes.
+- The system will sometimes refuse to call work "done" that a user feels is done;
+  this friction is intentional and is the product's main promise.
+
+---
+
+## ADR-004: Quality enforced by 8 gates and a blind multi-reviewer council
+
+**Status:** Accepted
+
+### Context
+
+Autonomous code generation without enforcement produces plausible-looking but
+incorrect output. A single reviewer (human or model) is prone to sycophancy and
+blind spots. Quality has to be enforced mechanically and from independent angles,
+not trusted.
+
+### Decision
+
+Run 8 quality gates (static analysis, test pass/fail, blind 3-reviewer code
+review with severity blocking, anti-sycophancy / devil's advocate, mock-integrity
+detection, test-mutation detection, documentation coverage, magic-modules debate)
+plus a conditional legacy-healing auditor. Code review uses three independent
+reviewers whose verdicts must reconcile; Critical/High findings block, Medium/Low
+are advisory. An override council can revisit a BLOCK only when backed by a
+non-empty evidence artifact.
+
+### Consequences
+
+- A red gate stops the release; "2-of-3 is good enough" is explicitly not
+  acceptable for the council, which loops until unanimous.
+- Gates add latency and token cost to every iteration, accepted as the price of
+  trustworthy output.
+- Each gate's blocking semantics must be precise; an over-eager gate that fires on
+  unrelated changes (as the legacy-healing auditor once did) erodes signal and was
+  scoped to fire only on healing-mode work.
+
+---
+
+## ADR-005: File-based memory in `.loki/` as the system's source of truth
+
+**Status:** Accepted
+
+### Context
+
+The orchestrator, dashboard, MCP server, and quality gates are separate processes
+(and separate runtimes: bash, TypeScript, Python). They need shared, durable state
+that survives crashes and resumes, without forcing an external database as a
+prerequisite for a local-first tool.
+
+### Decision
+
+All components communicate through filesystem state under `.loki/` (memory,
+session, queue, checkpoints, findings, healing artifacts). Memory is a layered
+Python package (`memory/`) with episodic, semantic, and procedural stores,
+progressive-disclosure loading, optional vector search, and cross-project recall.
+A unified event bus (`events/`) provides Python, TypeScript, and bash emitters
+over the same conventions.
+
+### Consequences
+
+- Any process can read or resume from disk; runs survive restarts and pod loss.
+- Concurrent writers must coordinate via file locking; lost-update and inode races
+  here have been recurring, high-severity bug classes that demand careful locking
+  and tests.
+- No database is required to run locally, preserving the self-hosted, private,
+  zero-egress posture; external stores (e.g. ChromaDB, object storage) are optional
+  add-ons, not dependencies.
+
+---
+
+## ADR-006: Polyglot stack (Bun/TypeScript, Python, bash) over a single language
+
+**Status:** Accepted
+
+### Context
+
+The system spans distinct concerns: orchestration control flow, a web dashboard
+API, a memory engine with embeddings, an MCP server, and provider shims. No single
+language is the best fit for all of them, and parts predate the Bun migration.
+
+### Decision
+
+Use the right tool per concern: Bun/TypeScript for the orchestrator, CLI, and HTTP
+API (`loki-ts/`, `api/`); Python for the memory engine, MCP server, and FastAPI
+dashboard (`memory/`, `mcp/`, `dashboard/`); bash for provider configs, hooks, and
+the legacy runtime during migration. Node.js 20+ is the minimum engine; the npm
+package ships zero runtime dependencies in `package.json`.
+
+### Consequences
+
+- Contributors need familiarity with more than one ecosystem, and CI must run a
+  matrix across runtimes (bun typecheck/test, Python syntax, shellcheck, parity).
+- Cross-language contracts (the `.loki/` state files, the event bus) must be kept
+  in sync across three emitter implementations.
+- Boundaries stay clean because each component owns its language; the cost is more
+  build and test tooling, mitigated by the local CI gate.
+
+---
+
+## ADR-007: Distribute across npm, Docker, and Homebrew from a single release pipeline
+
+**Status:** Accepted
+
+### Context
+
+Users install via different channels (npm global, Docker, Homebrew), and the
+dashboard frontend and Python modules must be present and working in each. Past
+releases shipped broken because local testing did not verify the published
+tarball or a fresh global install.
+
+### Decision
+
+A single GitHub Actions release workflow creates the tag and GitHub Release, then
+publishes to npm, builds and pushes a multi-arch (amd64 + arm64) Docker image, and
+updates the Homebrew tap. Every release is preceded by a mandatory local CI gate
+(`scripts/local-ci.sh`) that mirrors every CI workflow, plus pre-publish
+validation that inspects the npm tarball contents and performs a fresh global
+install smoke test. Versions are kept in sync across all manifests and Dockerfiles.
+
+### Consequences
+
+- The local Mac is the canonical pre-push gate; GitHub Actions is the verifier, not
+  the place defects are discovered.
+- The dashboard frontend must be rebuilt and committed before release, and the
+  built artifacts must be tracked in git so every channel includes them.
+- A single broken artifact can affect all channels at once, so the validation
+  checklist is non-negotiable per release.
+
+---
+
+## ADR-008: Source-available under BUSL-1.1 with a separate commercial brand
+
+**Status:** Accepted
+
+### Context
+
+The project needs broad adoption and community trust (which favors open source)
+while leaving room for a sustainable commercial business and protection against
+hosted-competitor free-riding.
+
+### Decision
+
+License the source under the Business Source License 1.1: free for personal,
+internal, and academic use, source-available, with commercial hosted/team
+editions sold under the separate **Autonomi** brand (Autonomi Cloud, Autonomi
+Enterprise). The same Loki CLI, SDK, and MCP are available to everyone.
+
+### Consequences
+
+- BUSL-1.1 is not OSI-approved "open source"; the project consistently uses the
+  term "source-available" to avoid misleading users.
+- Contributions require a CLA (`CLA.md`), adding friction for contributors in
+  exchange for a clear commercial path.
+- The open core and commercial editions must stay aligned on the core surface so
+  the free tier remains genuinely useful, not a crippled demo.
+
+---
+
+## ADR-009: Model selection tiered by task, with deterministic auto-selection
+
+**Status:** Accepted
+
+### Context
+
+Using the most capable (and expensive) model for every task wastes budget; using
+a weak model for architecture produces poor results. Forcing the user to choose a
+model per task is friction and contradicts the autonomy goal.
+
+### Decision
+
+Map task type to model tier: Opus for planning and architecture, Sonnet for
+development and functional testing, Haiku for unit tests, monitoring, and simple
+parallelizable work. The tier is auto-selected from task signals
+(`run.sh:get_rarv_tier()`, `detect_complexity()`) rather than asked of the user;
+model levers (session pin, mid-flight override, ceiling) exist as opt-out escape
+hatches, and the cost quote, dashboard, and dispatched model always agree.
+
+### Consequences
+
+- Cost scales with task difficulty automatically, and parallel cheap-model work is
+  encouraged for throughput.
+- Selection must be deterministic and honest: the quoted plan cost and the actual
+  dispatch must never diverge, including ceiling-enforcement and tier-collapse
+  paths (e.g. an unavailable Fable tier collapsing to Opus).
+- Adding or retiring a model means updating the registry and the auto-select
+  heuristic together, or quotes drift from reality.
+
+---
+
+## ADR-010: Progressive-disclosure skill architecture for the agent context
+
+**Status:** Accepted
+
+### Context
+
+Loading the full body of operational guidance (quality gates, healing, testing,
+agent types, provider docs, advanced patterns) into every agent invocation would
+waste context budget and dilute the signal. But the guidance still needs to be
+available on demand.
+
+### Decision
+
+Keep `SKILL.md` slim (a few hundred lines) and split detailed guidance into
+on-demand modules under `skills/`, with an index (`skills/00-index.md`) that routes
+to the right module, and deeper reference material under `references/`. Modules are
+pulled in only when relevant to the current task.
+
+### Consequences
+
+- Context stays focused and cheaper per iteration; agents read only what the task
+  needs.
+- The routing index and module boundaries must be maintained, or guidance becomes
+  hard to find and modules drift out of sync with the code they describe.
+- `SKILL.md` has a hard size budget; detailed content belongs in modules, not
+  inlined, which is enforced as a contribution rule.