loki-mode 11.3.0 → 11.3.2

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.

package/docs/audit-logging.md

@@ -6,7 +6,7 @@ Audit trails for Loki Mode operations.
 
 ## Overview
 
-Audit logging captures significant events for security monitoring, debugging, and usage analytics. Audit logging is **enabled by default** as of v5.37.0.
+Audit logging captures significant events for security monitoring, debugging, and usage analytics. Audit logging is **enabled by default**.
 
 ## Configuration
 
@@ -31,7 +31,7 @@ enterprise:
     retention_days: 90         # Days to keep logs
     max_file_size: 100         # MB per file before rotation
     compress: true             # Compress rotated files
-    integrity_check: true      # Enable SHA-256 chain hashing (v5.38.0)
+    integrity_check: true      # Enable SHA-256 chain hashing
     syslog_enabled: false      # Forward to external syslog
     exclude_events:            # Events to exclude
       - api.request
@@ -123,7 +123,7 @@ Audit logs use JSON Lines format (one JSON object per line):
   "metadata": {
     "hostname": "dev-machine",
     "pid": 12345,
-    "version": "5.42.2"
+    "version": "X.Y.Z"
   }
 }
 ```
@@ -139,7 +139,7 @@ Audit logs use JSON Lines format (one JSON object per line):
 | `resource` | string | Resource affected (optional) |
 | `details` | object | Event-specific details |
 | `metadata` | object | System metadata (hostname, PID, version) |
-| `chain_hash` | string | SHA-256 chain hash for integrity (v5.38.0) |
+| `chain_hash` | string | SHA-256 chain hash for integrity |
 
 ## Log Location
 
@@ -278,7 +278,7 @@ Response:
 }
 ```
 
-## Log Integrity (v5.38.0)
+## Log Integrity
 
 Audit entries are chain-hashed with SHA-256 for tamper detection.
 
@@ -325,7 +325,7 @@ empty chain.
 export LOKI_AUDIT_NO_INTEGRITY=true
 ```
 
-## SIEM Integration (v5.38.0)
+## SIEM Integration
 
 ### Syslog Forwarding
 
@@ -392,7 +392,7 @@ EOF
 systemctl restart filebeat
 ```
 
-## Agent Action Audit (v5.38.0)
+## Agent Action Audit
 
 In addition to dashboard audit logs, agent actions are tracked separately.
 

package/docs/authentication.md

@@ -9,7 +9,7 @@ Authentication and access control for Loki Mode dashboard and API.
 Loki Mode supports two authentication methods:
 
 1. **Token-based authentication** - API tokens with scopes and expiration
-2. **OIDC/SSO integration** (v5.36.0) - Google, Azure AD, Okta
+2. **OIDC/SSO integration** - Google, Azure AD, Okta
 
 Both methods can be enabled simultaneously and provide access to the dashboard API at `http://localhost:57374` (or `https://` with TLS enabled).
 
@@ -97,7 +97,7 @@ Scope hierarchy:
 - `control` includes `write` and `read`
 - `write` includes `read`
 
-### Roles (v5.37.0)
+### Roles
 
 Predefined roles map to common access patterns:
 
@@ -120,7 +120,7 @@ Generate token with custom scopes:
 loki enterprise token generate custom-bot --scopes "read,audit" --expires 30
 ```
 
-## OIDC/SSO Authentication (v5.36.0)
+## OIDC/SSO Authentication
 
 Enterprise identity provider integration for centralized authentication.
 

package/docs/authorization.md

@@ -2,7 +2,7 @@
 
 > **Control Plane migration:** the classic dashboard UI and port 57374 are removed in Loki Mode 10.8; the UI is the Control Plane (`loki dashboard`, default port 47821). Examples below that use port 57374 or `/api/*` describe the legacy API server. See [control-plane-migration.md](control-plane-migration.md) for the `/v1/*` mapping and what is not yet available.
 
-Role-based access control (RBAC) for Loki Mode (v5.37.0).
+Role-based access control (RBAC) for Loki Mode.
 
 ## Overview
 

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

@@ -14,10 +14,10 @@ Deploy Loki Mode using Docker Compose, verify the dashboard is accessible, and c
 
 ## Step 1: Review the Docker Compose Configuration
 
-Examine the `docker-compose.yml` at the repository root:
+Examine `docker/docker-compose.yml`:
 
 ```bash
-cat docker-compose.yml
+cat docker/docker-compose.yml
 ```
 
 Key elements to note:
@@ -32,7 +32,7 @@ Key elements to note:
 docker-compose build
 ```
 
-This builds from the `Dockerfile` which installs:
+This builds from `docker/Dockerfile`, which installs:
 - Ubuntu 24.04 base
 - Node.js 20 LTS
 - Python 3 with venv support
@@ -68,7 +68,7 @@ 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 \
+ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY docker compose -f docker/docker-compose.yml run \
   -e ANTHROPIC_API_KEY \
   loki start ./prd.md
 ```
@@ -96,7 +96,7 @@ Test resource configuration by modifying environment variables:
 
 ```bash
 # Run with budget limit and reduced parallel agents
-docker-compose run \
+docker compose -f docker/docker-compose.yml run \
   -e ANTHROPIC_API_KEY \
   -e LOKI_BUDGET_LIMIT=5.00 \
   -e LOKI_MAX_PARALLEL_AGENTS=3 \
@@ -141,7 +141,7 @@ loki secrets status
 ## Verification Checklist
 
 - [ ] `docker-compose build` completes without errors
-- [ ] `docker-compose run loki version` outputs the correct version
+- [ ] `docker compose -f docker/docker-compose.yml 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)

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

@@ -28,11 +28,11 @@ docker pull asklokesh/loki-mode:5.52.0
 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.
+The Dockerfile is `docker/Dockerfile`. A separate `docker/Dockerfile.sandbox` exists for sandboxed execution.
 
 ### Docker Compose
 
-The `docker-compose.yml` at the repository root provides a ready-to-use configuration:
+`docker/docker-compose.yml` provides a ready-to-use configuration:
 
 ```yaml
 services:
@@ -59,7 +59,7 @@ services:
 Start with:
 
 ```bash
-docker-compose run loki start ./prd.md
+docker compose -f docker/docker-compose.yml run loki start ./prd.md
 ```
 
 Key volume mounts:
@@ -86,7 +86,7 @@ Or pass `--sandbox` to the start command:
 loki start --sandbox ./prd.md
 ```
 
-The sandbox uses `Dockerfile.sandbox` which adds additional isolation constraints.
+The sandbox uses `docker/Dockerfile.sandbox` which adds additional isolation constraints.
 
 ## Security Hardening
 

package/docs/certification/README.md

@@ -26,7 +26,7 @@ The Autonomi Certified Developer certification validates your knowledge of Loki
 
 - Familiarity with command-line tools (bash, git, npm)
 - Basic understanding of AI/LLM concepts (prompts, models, tokens)
-- Node.js 18+ installed
+- Node.js 20+ installed
 - A supported AI provider CLI installed (Claude Code, Cline, Codex CLI, Aider, or opencode)
 
 ## How to Use This Program

package/docs/control-plane-container.md

@@ -1,7 +1,7 @@
 # Run the Control Plane in a container
 
 The Control Plane (run ingest API plus UI) ships as its own small image built
-from `Dockerfile.control-plane`. It serves on port 47821, stores its SQLite
+from `docker/Dockerfile.control-plane`. It serves on port 47821, stores its SQLite
 database under `/data`, runs as a non-root user and contains no secrets.
 
 The image binds 0.0.0.0, so `LOKI_CONTROL_TOKEN` is required at run time. Without
@@ -13,7 +13,7 @@ server prints a warning when you do.
 ## Docker
 
 ```bash
-docker build -f Dockerfile.control-plane -t loki-control-plane .
+docker build -f docker/Dockerfile.control-plane -t loki-control-plane .
 docker run -d -p 47821:47821 -e LOKI_CONTROL_TOKEN="$(openssl rand -hex 32)" -v loki-control:/data loki-control-plane
 LOKI_CONTROL_URL=http://localhost:47821 loki control status
 ```

package/docs/dev/real-run.md

@@ -0,0 +1,34 @@
+# real-run: real scenarios against the installed tarball
+
+`scripts/real-run.sh <scenario>` exists because every real bug found in the D91 push came from a real run, not a fixture. It never touches the repo checkout: it runs `npm pack --ignore-scripts` (so the committed `loki-ts/dist` is what ships), installs the tarball into a temp prefix under a run-owned temp dir, and runs the scenario with `LOKI_NO_SKILL_LINK_HEAL=1 LOKI_NO_BROWSER=1` against that installed `loki`.
+
+## Usage
+
+```bash
+bash scripts/real-run.sh --dry trivial-sum        # pack + install + fixture, no model call (CI-safe)
+bash scripts/real-run.sh --validate router-on      # parse the scenario file only
+bash scripts/real-run.sh --check-receipt R.json trivial-sum   # apply receipt assertions to a file
+bash scripts/real-run.sh --tsv-out results.tsv trivial-sum    # BILLED: real model run
+```
+
+Env: `REAL_RUN_TARBALL` reuses a tarball, `REAL_RUN_TIMEOUT` (default 1200s) bounds the loki call, `REAL_RUN_SCENARIO_DIR` overrides the scenario directory, `REAL_RUN_TSV` is the default for `--tsv-out`.
+
+## Scenarios
+
+Files `tests/real-run/scenarios/<name>.sh`, sourced by the script. Shipped: `trivial-sum` (about $0.10), `two-bug`, `attempts-2`, `router-on`, `issues-dry-run` (needs network, no model).
+
+| Variable | Meaning |
+| --- | --- |
+| `SC_DESC` | one line description |
+| `SC_BILLED` | 1 if the scenario calls a model |
+| `SC_FIXTURE` | generator name under `scripts/b9-fixtures/` (`trivial-sum`, `two-bug`) |
+| `SC_ARGS` | array of loki arguments |
+| `SC_ENV` | array of `NAME=value` entries |
+| `SC_RECEIPT` | array of assertions on the newest `.loki/runs/*/receipt.json`: `path == v`, `!=`, `<=`, `>=`, or `path exists` (dotted path, for example `cost.usd`) |
+| `SC_CONSOLE` | array of extended regexes that must match the console output |
+
+## Output
+
+One `PASS`/`FAIL` line per assertion; exit 1 on any FAIL, 2 on usage or scenario errors. A TSV line is printed (and appended with `--tsv-out`): `ts scenario verdict wall_s cost_usd input_tokens output_tokens result`. Fields the receipt does not carry are `NA`, never 0. B9 and the 10x metrics can reuse the TSV.
+
+`tests/test-real-run.sh` covers scenario parsing, the `--dry` install from the packed tarball, and assertion failure on a doctored receipt.

package/docs/dev/release-checklist.md

@@ -45,7 +45,7 @@ VERSION                                  # Single line: X.Y.Z
 package.json                             # "version": "X.Y.Z"
 SKILL.md                                 # Header (line ~6) AND footer (last line)
 Dockerfile                               # LABEL version= AND org.opencontainers.image.version (both, or it drifts)
-Dockerfile.sandbox                       # Same two labels
+docker/Dockerfile.sandbox                # Same two labels
 plugins/loki-mode/.claude-plugin/plugin.json  # "version": "X.Y.Z" (marketplace.json carries no version)
 server.json                              # "version" AND packages[loki-mode].version (MCP registry manifest; enforced by tests/test-server-json-current.sh)
 vscode-extension/package.json            # DEPRECATED v7.2.0, no longer published; bump only if vendoring
@@ -55,7 +55,7 @@ mcp/__init__.py                          # __version__ = "X.Y.Z"
 CHANGELOG.md                             # Add new version entry at top
 docs/INSTALLATION.md                     # Version header
 wiki/Home.md, wiki/_Sidebar.md, wiki/API-Reference.md
-README.md, docker-compose.yml            # Docker image tags (MAJOR/MINOR bumps)
+README.md, docker/docker-compose.yml            # Docker image tags (MAJOR/MINOR bumps)
 ```
 
 The CHANGELOG.md entry must be a full section, not a one-line placeholder

package/docs/environment-variables.md

@@ -135,6 +135,7 @@ banners you might expect. These variables control the remaining `[INFO]` and
 | `LOKI_DURABLE_STATE` | `0` | `1` enables durable state **and** the richer process-exit contract that lets Kubernetes distinguish a deterministic failure from a crash. See [exit codes](./exit-codes.md). |
 | `LOKI_SDK_LOOP` | unset | Routes the run through the Bun/TypeScript runner instead of bash. Both implement the same exit contract. |
 | `LOKI_ALLOW_AGENT_GITHUB_TOKEN` | unset | By default `GH_TOKEN`, `GITHUB_TOKEN`, `GH_ENTERPRISE_TOKEN`, and `GITHUB_ENTERPRISE_TOKEN` are withheld from agent sessions. The two routes differ: on the bash route (`autonomy/run.sh`) the withheld tokens are re-granted only for Loki's own trusted calls, namely the `gh()` CLI wrapper, the `_loki_net` helper used by the optional local-PR path in `on_run_complete()`, the session-end `create_session_pr` call, and `autonomy/lib/proof-check.sh`'s network probe. On the Bun route (`loki-ts/src/runner/github_token.ts`'s `withholdGithubTokens()`) the tokens are dropped from the process outright, with no re-grant and no push/PR step of its own. Exactly `1` lets the agent inherit the tokens as before, on either route; that is a Rule of Two exposure, and a one-line stderr warning is printed. |
+| `LOKI_AI_MARKING` | unset (off) | `1` (exactly) adds machine-readable trailers to the Loki commit (`AI-Generated: true`, `AI-Provider`, `AI-Model`, `Loki-Receipt`, after `Loki-Run`) and one `AI-Generated: true (...)` marker line under the verdict in the PR body. Values are single-line and bounded. Off, the commit and PR body are byte-identical to before. |
 
 `LOKI_DURABLE_STATE=1` is the one to set in a Job or task definition. Without
 it every failure collapses to exit 1 and the platform cannot tell "re-running

package/docs/exit-codes.md

@@ -142,7 +142,7 @@ An early draft spec listed `1=BLOCKED, 2=CONCERNS`. That ordering was rejected:
 it is not used anywhere, it has no consumers, and it inverts the
 severity-rises-with-the-code rule that every other command follows.
 
-### Known gaps until v10.0.0
+### Known gaps
 
 The table above is the target. On the current release, three inputs do not
 return what it implies. Measured on this checkout:
@@ -153,8 +153,8 @@ return what it implies. Measured on this checkout:
 | Not a git directory | `loki verify` | 1 (CONCERNS) | 2 |
 | Unknown flag | `loki verify --no-such-flag` | 3 | 64 |
 
-The gap is tracked as the pending moat case P2.verify-exit-contract,
-milestone v10.0.0, in `tests/moat/pending.txt`.
+The gap is tracked as the pending moat case P2.verify-exit-contract in
+`tests/moat/pending.txt`.
 
 ### `loki verify --fast`
 

package/docs/git-workflow.md

@@ -1,12 +1,12 @@
 # Git Workflow
 
-Branch protection and Git best practices for Loki Mode (v5.37.0).
+Branch protection and Git best practices for Loki Mode.
 
 ## Overview
 
 Loki Mode includes branch protection features that prevent direct commits to main/master branches and enforce a clean PR-based workflow. This ensures code review, quality gates, and audit trails for all changes made by autonomous agents.
 
-## Branch Protection (v5.37.0)
+## Branch Protection
 
 ### Enable Branch Protection
 
@@ -388,4 +388,4 @@ git log --show-signature
 - [Audit Logging](audit-logging.md) - Track Git operations
 - [GitHub Integration](../skills/github-integration.md) - Issue import and PR creation
 - [Enterprise Features](../wiki/Enterprise-Features.md) - Branch protection setup
-- [Contributing](../CONTRIBUTING.md) - Contribution guidelines
+- [Contributing](../.github/CONTRIBUTING.md) - Contribution guidelines