loki-mode 11.5.1 → 11.7.1

package/docs/authentication.md

@@ -97,6 +97,20 @@ Scope hierarchy:
 - `control` includes `write` and `read`
 - `write` includes `read`
 
+### Key Rotation and Revocation
+
+Dashboard API keys (`/api/keys`) can be rotated with a grace period during which the old key stays valid (default 24 hours, `grace_period_hours`):
+
+```bash
+curl -X POST http://localhost:57374/api/keys/ci-pipeline/rotate \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"grace_period_hours": 24}'
+
+curl -X DELETE http://localhost:57374/api/keys/ci-pipeline \
+  -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
 ### Roles
 
 Predefined roles map to common access patterns:
@@ -177,7 +191,11 @@ Running with signature verification off provides no authentication security.
 4. Provider redirects back with JWT
 5. Dashboard validates JWT and grants access
 
-OIDC-authenticated users receive full access scopes by default. For fine-grained control, combine OIDC with token-based authorization.
+OIDC-authenticated users are NOT granted full access by default. The role is resolved from claims (see below) and its scopes are enforced through the same hierarchy as API tokens.
+
+### OIDC Role Claims
+
+Role claims are read case-insensitively; values may be a string, a space-separated string or a list. Sources: the claim named by `LOKI_OIDC_ROLES_CLAIM` (dotted paths such as `realm_access.roles` work), then `roles`, `groups`, `realm_access.roles` (Keycloak) and `cognito:groups` (AWS Cognito). Only values that exactly match a built-in role name (`admin`, `operator`, `viewer`, `auditor`) grant that role; other group names fall through to `LOKI_OIDC_DEFAULT_ROLE`. When several roles match, the highest privilege wins (`admin` > `operator` > `auditor` > `viewer`). An unset or unrecognized default falls back to `viewer`, never `admin`. When PyJWT and cryptography are installed, the signature (RS256/RS384/RS512), issuer, audience and expiry are verified against the issuer JWKS.
 
 ### Mixed Mode
 

package/docs/dev/architecture-reference.md

@@ -105,3 +105,11 @@ These knobs together implement the RARV-C (closure) loop: findings -> override c
 ## Project memory across runs
 
 extract_learnings_from_session (autonomy/run.sh) mirrors learnings and decisions into .loki/memory/learnings/project-*.jsonl. get_relevant_learnings adds a bounded newest-first project_memory list (15 entries, LOKI_PROJECT_MEMORY_MAX_CHARS, default 2000) to .loki/state/relevant-learnings.json at run start. LOKI_PROJECT_MEMORY=0 disables both. Test: tests/test-project-memory.sh.
+
+## Verdicts, composite receipts and the autonomy ladder (v11.7.0)
+- Two sets: receipt verdicts (`engine10/types.ts` Verdict: VERIFIED, PARTIAL, ALREADY_SATISFIED, SPEC_CONFLICT, FAILED) and run outcomes (`engine10/output.ts` Outcome adds BUDGET_STOP, BLOCKED, STALLED, CANCELLED; exit ladder EXIT). Only receipt verdicts are sealed.
+- Composite: `features/speed/seal_group.ts` composeComposite/verifyComposite (schema `loki.v10.composite/1`), sealed by `loki verify --seal-composite <run_dir>`, signed with the existing `signReceipt`, capped by `capGroupVerdict`. Workspace runs seal it after integration.json.
+- Autonomy ladder: `src/policies/engine.js` allowedActions(level) (propose = none, execute = pr, operate = pr + deploy; merge never). engine10 `supervisor.ts` prGate consults `src/policies/check.js`; `loki deploy --execute` consults it for `deploy` and fails closed. `loki trust` graduationAdvice is advisory and never writes the policy file.
+- Parallel units: `route.ts` maybeRunGroup defaults to `features/speed/run_group.ts`, which freezes per-unit acceptance (`features/contract.ts`), runs units, merges with `engine10/integrate.ts` and seals once via sealGroup.
+- Lessons: every sealed run appends a receipt fact (`LOKI_AUTO_LEARN_PR`, default on) outside the receipt body; `implement.ts` injects lessons and relevant learnings inside the untrusted-data fence; `loki memory brief --task T` prints the same block.
+

package/docs/dev/release-checklist.md

@@ -4,9 +4,10 @@ Moved out of CLAUDE.md (S-78) to keep the root file short. Updated in this
 pass to remove two items that `docs/v10/DECISIONS.md` D25 and
 `docs/LOKI-10-BUILD-PROMPT.md` section 1 have superseded:
 - `git add -A` in step 4 is replaced with staging by name (repo rule, always).
-- Per-merge pushing is replaced by the release-train model (D25): batch
-  approved merges locally, push once per train, freeze main until Tests, Bun
-  Parity and Security Audit are all green on that exact SHA, then release.
+- Per-merge pushing and the D25 release trains are superseded by D96 (every
+  approved slice is a release; see `docs/v10/OPERATING-MODEL.md`). Waiting for
+  Tests and Security Audit green on that exact SHA still applies to any push
+  made outside the merge-gate.
   "Wait for user approval before commit" from the old workflow is superseded
   by the standing authorization in `docs/LOKI-10-BUILD-PROMPT.md` section 1
   for sessions operating under that program; outside it, ask as normal.
@@ -116,13 +117,13 @@ rm -f loki-mode-*.tgz
 ```
 If any check fails, do not release; fix the root cause first.
 
-### 4. Commit and land (release-train model, D25)
+### 4. Commit and land (every approved slice is a release, D96)
 
 Stage files by name (never `git add -A` or `git add .`), commit with the
-repo-local `asklokesh` identity, no co-author. Batch approved merges locally;
-push once per train (`git push origin main`); wait for Tests and
-Security Audit to go green on that exact SHA before bumping VERSION and
-releasing. GitHub Actions then creates the tag, the GitHub Release, publishes
+repo-local `asklokesh` identity, no co-author. The merge-gate merges approved
+slices to main and main publishes to npm `next` (D96); for a manual push
+(`git push origin main`), wait for Tests and Security Audit to go green on that
+exact SHA before bumping VERSION and releasing. GitHub Actions then creates the tag, the GitHub Release, publishes
 npm, builds/pushes Docker, and updates the Homebrew tap. Do not manually
 create tags.
 

package/docs/enterprise/security.md

@@ -6,153 +6,9 @@
 
 Loki Mode's security model follows a defense-in-depth approach. All security features are opt-in via environment variables, with sensible defaults that prioritize safety. When enterprise auth is not configured, the system operates in local-only mode with no network exposure.
 
-## Authentication
+## Authentication and Authorization
 
-### Token Authentication
-
-The primary authentication method uses bearer tokens prefixed with `loki_`.
-
-**Configuration:**
-
-```bash
-# Enable token auth for the dashboard/control plane API
-export LOKI_ENTERPRISE_AUTH=true
-```
-
-**Token Lifecycle:**
-
-```bash
-# Create a new API key
-curl -X POST http://localhost:57374/api/keys \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "ci-pipeline", "role": "operator"}'
-
-# Rotate a key with 24-hour grace period
-curl -X POST http://localhost:57374/api/keys/ci-pipeline/rotate \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"grace_period_hours": 24}'
-
-# Revoke a key
-curl -X DELETE http://localhost:57374/api/keys/ci-pipeline \
-  -H "Authorization: Bearer $ADMIN_TOKEN"
-```
-
-**SDK Usage:**
-
-Python:
-```python
-from loki_mode_sdk import AutonomiClient
-
-client = AutonomiClient(
-    base_url="http://localhost:57374",
-    token="loki_your_token_here"
-)
-```
-
-TypeScript:
-```typescript
-import { AutonomiClient } from 'loki-mode-sdk';
-
-const client = new AutonomiClient({
-  baseUrl: 'http://localhost:57374',
-  token: 'loki_your_token_here'
-});
-```
-
-### OIDC / SSO Integration
-
-For organizations using identity providers (Okta, Auth0, Azure AD), Loki Mode supports OIDC-based authentication.
-
-**Configuration:**
-
-```bash
-export LOKI_OIDC_ISSUER="https://your-idp.okta.com/oauth2/default"
-export LOKI_OIDC_CLIENT_ID="your-client-id"
-# Optional: audience override (defaults to LOKI_OIDC_CLIENT_ID)
-export LOKI_OIDC_AUDIENCE="your-api-audience"
-```
-
-The system validates OIDC bearer tokens (presented as `Authorization: Bearer <jwt>`)
-against the issuer's JWKS endpoint. When PyJWT + cryptography are installed, the
-JWT signature is cryptographically verified (RS256/RS384/RS512) along with the
-issuer, audience, and expiry. Without PyJWT, tokens are rejected unless
-`LOKI_OIDC_SKIP_SIGNATURE_VERIFY=true` is set explicitly (insecure, local testing
-only).
-
-**Claims-to-roles mapping:**
-
-On a valid token, role/group claims are mapped to the four built-in Loki roles
-(`admin`, `operator`, `viewer`, `auditor`). The resolved role's scopes are then
-enforced through the same scope hierarchy used for API tokens. OIDC users are
-NOT granted full access by default.
-
-Recognized claim sources (case-insensitive; values may be a string,
-space-separated string, or list):
-
-| Claim | Provider |
-|-------|----------|
-| value of `LOKI_OIDC_ROLES_CLAIM` (supports dotted paths, e.g. `realm_access.roles`) | configurable |
-| `roles` | generic |
-| `groups` | generic |
-| `realm_access.roles` | Keycloak |
-| `cognito:groups` | AWS Cognito |
-
-Only claim values that exactly match a built-in role name (`admin`, `operator`,
-`viewer`, `auditor`) grant that role. Arbitrary group names (common in `groups`
-or `cognito:groups`) do not map to a role and fall through to the default.
-
-When multiple recognized roles are present, the highest-privilege match wins
-(precedence: `admin` > `operator` > `auditor` > `viewer`).
-
-**Default role (when no recognized role claim is present):**
-
-```bash
-# Defaults to the least-privileged role (viewer). Never admin.
-export LOKI_OIDC_DEFAULT_ROLE="viewer"
-```
-
-If `LOKI_OIDC_DEFAULT_ROLE` is unset or set to an unrecognized value, it falls
-back to `viewer`. The default is never `admin` / full access.
-
-## Authorization
-
-### Role-Based Access Control
-
-Four built-in roles provide scoped access:
-
-| Role | Scope | Permissions |
-|------|-------|-------------|
-| `admin` | Full control | Create/delete tenants, manage API keys, configure policies, all operator/viewer/auditor permissions |
-| `operator` | Execution | Start/cancel runs, create/update projects and tasks, read all resources |
-| `viewer` | Read-only | Read projects, runs, tasks, status. No write or delete operations |
-| `auditor` | Audit access | Read audit logs, verify chain integrity, generate compliance reports. No execution permissions |
-
-**Scope Hierarchy:**
-
-```
-admin > operator > viewer
-admin > auditor
-```
-
-Admin inherits all permissions. Operator inherits viewer permissions. Auditor is a separate branch with read-only access to audit data.
-
-**API Key Scopes:**
-
-API keys are created with a role assignment:
-
-```bash
-# Create a viewer key for monitoring dashboards
-curl -X POST http://localhost:57374/api/keys \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -d '{"name": "grafana-reader", "role": "viewer"}'
-
-# Create an operator key for CI pipelines
-curl -X POST http://localhost:57374/api/keys \
-  -H "Authorization: Bearer $ADMIN_TOKEN" \
-  -d '{"name": "github-actions", "role": "operator"}'
-```
+Token auth (`LOKI_ENTERPRISE_AUTH`), key rotation with a 24-hour grace period, OIDC/SSO claim mapping and the default viewer role are documented in [authentication.md](../authentication.md). Roles (`admin`, `operator`, `viewer`, `auditor`), scope hierarchy and API key scopes are in [authorization.md](../authorization.md).
 
 ## API Security
 
@@ -221,94 +77,7 @@ This is a deliberate fail-closed design. Invalid or missing signatures always re
 
 ## Audit Logging
 
-### Hash-Chained Audit Logs
-
-Audit logs use SHA-256 hash chains for tamper evidence. Each entry's hash depends on the previous entry's hash, creating an immutable chain from the genesis record.
-
-**JavaScript Audit (Agent Actions):**
-
-```
-.loki/audit/audit.jsonl
-```
-
-Each entry:
-```json
-{
-  "seq": 42,
-  "timestamp": "2026-02-21T10:00:00.000Z",
-  "who": "agent-1",
-  "what": "file_write",
-  "where": "src/app.js",
-  "why": "implement feature",
-  "previousHash": "abc123...",
-  "hash": "def456..."
-}
-```
-
-**Python Audit (Dashboard API):**
-
-```
-~/.loki/dashboard/audit/audit-2026-02-21.jsonl
-```
-
-Each entry:
-```json
-{
-  "timestamp": "2026-02-21T10:00:00.000Z",
-  "action": "create",
-  "resource_type": "project",
-  "resource_id": "proj-1",
-  "user_id": "admin",
-  "success": true,
-  "_integrity_hash": "abc123..."
-}
-```
-
-### Chain Verification
-
-JavaScript:
-```javascript
-const audit = require('./src/audit');
-audit.init('/path/to/project');
-const result = audit.verifyChain();
-// { valid: true, entries: 1542, brokenAt: null, error: null }
-```
-
-Python:
-```python
-from dashboard.audit import verify_log_integrity
-result = verify_log_integrity("/path/to/audit-2026-02-21.jsonl")
-# {"valid": True, "entries_checked": 1542, "first_tampered_line": None}
-```
-
-API:
-```bash
-curl http://localhost:57374/api/audit/verify \
-  -H "Authorization: Bearer $TOKEN"
-```
-
-### Syslog Forwarding
-
-Forward audit events to a centralized syslog server for SIEM integration:
-
-```bash
-export LOKI_AUDIT_SYSLOG_HOST="syslog.company.com"
-export LOKI_AUDIT_SYSLOG_PORT="514"          # default
-export LOKI_AUDIT_SYSLOG_PROTO="udp"         # or "tcp"
-```
-
-Security-relevant actions (`delete`, `kill`, `stop`, `login`, `logout`, `create_token`, `revoke_token`) are logged at `WARNING` level. All other actions are logged at `INFO` level.
-
-Syslog forwarding is fire-and-forget -- failures never block the main audit write path.
-
-### Log Rotation
-
-```bash
-export LOKI_AUDIT_MAX_SIZE_MB="10"    # Rotate when file exceeds this size
-export LOKI_AUDIT_MAX_FILES="10"      # Keep this many rotated files
-```
-
-Date-based log files (`audit-YYYY-MM-DD.jsonl`) are automatically rotated when they exceed the size limit. Old files are removed when the count exceeds the maximum.
+Hash-chained audit logs, chain verification, syslog forwarding (`LOKI_AUDIT_SYSLOG_*`) and rotation (`LOKI_AUDIT_MAX_SIZE_MB`, `LOKI_AUDIT_MAX_FILES`) are documented in [audit-logging.md](../audit-logging.md).
 
 ## Data Residency
 

package/docs/sentry-intake.md

@@ -11,3 +11,14 @@ From a URL (needs `SENTRY_AUTH_TOKEN`; without it nothing is fetched):
     SENTRY_AUTH_TOKEN=... loki start https://sentry.io/organizations/acme/issues/4001/
 
 The token is sent only to the Sentry host through a curl config on stdin, never on argv, and is never printed. Implementation: `autonomy/issue-providers.sh` (`normalize_sentry_json`).
+
+## Webhook: self-healing entry point
+
+`autonomy/trigger-server.py` accepts `POST /sentry`, a Sentry integration webhook authenticated by Sentry's own HMAC (`sentry-hook-signature`, hex HMAC-SHA256 of the body).
+
+1. Set the client secret: `LOKI_SENTRY_WEBHOOK_SECRET` (or `SENTRY_CLIENT_SECRET`). It must differ from the GitHub webhook secret and the API token. With no secret the route answers 503 and nothing is enqueued.
+2. Start the server: `python3 autonomy/trigger-server.py --port 8080` and point the Sentry alert webhook at `/sentry`.
+3. A valid alert is normalized with `normalize_sentry_json` and enqueues `loki start "<brief>" --pr --detach`. A bad signature gets 401.
+
+The output is a receipt-gated PR only, never a deploy. Whether the PR opens is still decided by the policy file (`autonomy`).
+