loki-mode 7.52.0 → 7.54.0

package/README.md

@@ -40,7 +40,7 @@ _The free, source-available autonomous coding agent by [Autonomi](https://www.au
 - **Legacy system healing** -- `loki modernize heal` archaeology/stabilize/isolate/modernize/validate phases (v6.67.0, see `skills/healing.md`)
 - **MCP server** -- 34 tools (including ChromaDB code search) plus 3 resources and 2 prompts (`mcp/server.py`, with magic tools registered from `mcp/magic_tools.py` and the managed-memory tool from `mcp/managed_tools.py`). Of the 34, 33 are always available; `loki_memory_redact` is registered but only succeeds when `LOKI_MANAGED_AGENTS=true` and `LOKI_MANAGED_MEMORY=true`. Launch with `loki mcp` (bootstraps the Python MCP SDK on first run).
 - **Full-stack output** -- Source code, tests, Docker Compose stacks (multi-service with healthchecks), CI/CD pipelines, audit logs
-- **Provider-agnostic** -- runs on Claude, Codex, Cline, or Aider with automatic failover (`loki-ts/src/runner/providers.ts`); no vendor lock-in. Gemini CLI deprecated v7.5.18; Antigravity CLI coming soon.
+- **Provider-agnostic** -- runs on Claude, Codex, Cline, or Aider with automatic failover (`loki-ts/src/runner/providers.ts`); no vendor lock-in. Gemini CLI deprecated v7.5.18.
 - **Source-available (BUSL-1.1)** -- Free for personal, internal, and academic use.
 
 ---
@@ -326,7 +326,6 @@ Loki's autonomy and quality loop are the product; the underlying coding CLI is s
 | **Cline CLI** | Experimental (Tier 2) | `-y` | Sequential | `npm i -g @anthropic-ai/cline` |
 | **Aider** | Experimental (Tier 3) | `--yes-always` | Sequential | `pip install aider-chat` |
 | **Google Gemini CLI** | DEPRECATED v7.5.18 | -- | -- | Upstream deprecated; runtime removed. `LOKI_PROVIDER=gemini` exits with migration message. |
-| **Anthropic Antigravity CLI** | Coming soon | -- | -- | Integration planned. |
 
 Status legend: "E2E-verified" means we run real spec-to-code builds on it ourselves. Claude Code is the primary, fully supported provider and the one Loki Mode is built for; it gets full features (subagents, parallelization, MCP, Task tool). "Experimental" means the wiring is in place but we have not produced an end-to-end verified build ourselves; treat as community-tested. Experimental providers run sequentially. Auto-failover switches providers when rate-limited. See [Provider Guide](skills/providers.md).
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.52.0
+# Loki Mode v7.54.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -238,7 +238,6 @@ loki docker --image IMG start prd.md          # override the image
 - **Cline**: Multi-provider CLI, degraded mode (sequential only, no Task tool)
 - **Aider**: 18+ provider backends, degraded mode (sequential only, no Task tool)
 - **Google Gemini CLI**: DEPRECATED starting v7.5.18 (upstream deprecated; runtime removed)
-- **Anthropic Antigravity CLI**: Coming soon
 
 ---
 
@@ -407,4 +406,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.52.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.54.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.52.0
+7.54.0

package/autonomy/loki

@@ -743,7 +743,7 @@ show_help() {
     echo "  --complex        Force complex complexity tier (8 phases)"
     echo "  --github         Enable GitHub issue import"
     echo "  --no-dashboard   Disable web dashboard"
-    echo "  --sandbox        Run in Docker sandbox for isolation"
+    echo "  --sandbox        Run in Docker sandbox for isolation (default: off; requires Docker)"
     echo "  --skip-memory    Skip loading memory context at startup"
     echo "  --fresh-prd      Regenerate the PRD from the codebase (no-PRD runs; ignores the reusable generated PRD)"
     echo "  --compliance PRESET  Enable compliance mode (default|healthcare|fintech|government)"
@@ -1063,7 +1063,7 @@ cmd_start() {
                 echo "  --github              Enable GitHub issue import"
                 echo "  --no-dashboard        Disable web dashboard"
                 echo "  --api                 Start dashboard API server alongside the build"
-                echo "  --sandbox             Run in Docker sandbox"
+                echo "  --sandbox             Run in Docker sandbox (default: off; requires Docker)"
                 echo "  --skip-memory         Skip loading memory context at startup"
                 echo "  --fresh-prd           Regenerate the PRD from the codebase on a no-PRD run"
                 echo "                        (ignores the reusable generated PRD; aliases: --regen-prd,"
@@ -5680,7 +5680,7 @@ cmd_run() {
                 echo "  --simple           Force simple complexity tier"
                 echo "  --complex          Force complex complexity tier"
                 echo "  --no-dashboard     Disable web dashboard"
-                echo "  --sandbox          Run in Docker sandbox"
+                echo "  --sandbox          Run in Docker sandbox (default: off; requires Docker)"
                 echo "  --no-plan          Skip auto-shown PRD analysis at startup"
                 echo "  --budget USD       Set cost budget limit"
                 echo ""

package/autonomy/prd-checklist.sh

@@ -422,7 +422,11 @@ checklist_should_verify() {
 # non-cooperative agent with filesystem tools can read the reservation directly.
 #
 # Selection is idempotent and reproducible: count = clamp(round(0.25*N), 1, 5)
-# for N>=4 items; ordering by sha256 of each item's "id" (stable, not random).
+# for N>=2 items; ordering by sha256 of each item's "id" (stable, not random).
+# Small checklists (2 <= N < 4) reserve exactly 1 held-out item via the same
+# sha256-rank selection (the clamp floor of 1 guarantees coverage), so a small
+# spec's checklist is never fully gameable. N<2 is a no-op: holding out the only
+# item of a 1-item checklist would leave nothing to verify against in the loop.
 # Written once to .loki/checklist/held-out.json; never overwritten if present.
 checklist_select_heldout() {
     local heldout_file="${CHECKLIST_DIR:-".loki/checklist"}/held-out.json"
@@ -442,7 +446,7 @@ checklist_select_heldout() {
     #   PARTIAL kept=k dropped=d - some prior ids survived; we keep only survivors
     #   DUP_SKIP          - current checklist ids are not unique; the id-based
     #                       mechanism is unsound, so we reserve nothing (MEDIUM-2)
-    #   NOOP              - n<4 with no prior file, or other no-write outcome
+    #   NOOP              - n<2 with no prior file, or other no-write outcome
     # Honest caveat: re-selection or partial-survival after a regen can reserve
     # items the build loop already saw in earlier prompts (the hidden-from-loop
     # guarantee is best-effort once the checklist ids change mid-run).
@@ -512,7 +516,7 @@ if os.path.exists(out_path):
 
 if prior is not None:
     prior_ids = [i for i in prior.get('held_out', []) if i]
-    # A prior reservation of [] (e.g. an earlier n<4 run) is a valid no-op state;
+    # A prior reservation of [] (e.g. an earlier n<2 run) is a valid no-op state;
     # keep it idempotent rather than re-selecting now that n may have grown.
     if not prior_ids:
         print('IDEMPOTENT')
@@ -525,9 +529,11 @@ if prior is not None:
     if not survivors:
         # Fully stale: the checklist regenerated and orphaned the reservation.
         # Deterministically re-select from the CURRENT checklist.
-        if n < 4:
+        if n < 2:
+            # N<2: cannot hold out from a 1-item checklist (reserving the only
+            # item leaves nothing to verify against). No-op write of an empty set.
             atomic_write({'held_out': [], 'total_items': n,
-                          'note': 'n<4: no held-out reserved (re-selected after stale reservation)'})
+                          'note': 'n<2: no held-out reserved (re-selected after stale reservation)'})
             print('RESELECTED 0')
             sys.exit(0)
         held = fresh_selection()
@@ -542,11 +548,15 @@ if prior is not None:
     sys.exit(0)
 
 # No prior reservation: first selection.
-if n < 4:
-    # N>=4 gate: smaller checklists get no held-out (nothing to hide reliably).
-    atomic_write({'held_out': [], 'total_items': n, 'note': 'n<4: no held-out reserved'})
+if n < 2:
+    # N<2 gate: a 1-item (or empty) checklist cannot meaningfully hold out an
+    # item -- reserving the only item would leave nothing to verify against in
+    # the build loop. Write an empty set so downstream reads stay well-formed.
+    atomic_write({'held_out': [], 'total_items': n, 'note': 'n<2: no held-out reserved'})
     print('NOOP')
     sys.exit(0)
+# For 2 <= N < 4, fresh_selection() reserves exactly 1 item (select_count clamps
+# round(0.25*N) up to a floor of 1), so small specs are never fully gameable.
 
 held = fresh_selection()
 atomic_write({'held_out': held, 'total_items': n})

package/autonomy/run.sh

@@ -585,7 +585,7 @@ BACKGROUND_MODE=${LOKI_BACKGROUND:-false}                # Run in background
 STAGED_AUTONOMY=${LOKI_STAGED_AUTONOMY:-false}           # Require plan approval
 AUDIT_LOG_ENABLED=${LOKI_AUDIT_LOG:-true}                # Enable audit logging (on by default)
 MAX_PARALLEL_AGENTS=${LOKI_MAX_PARALLEL_AGENTS:-10}      # Limit concurrent agents
-SANDBOX_MODE=${LOKI_SANDBOX_MODE:-false}                 # Docker sandbox mode
+SANDBOX_MODE=${LOKI_SANDBOX_MODE:-false}                 # Docker sandbox mode (informational; the real dispatch reads LOKI_SANDBOX_MODE at autonomy/loki:1965 and execs sandbox.sh -- this var is not consumed in run.sh)
 ALLOWED_PATHS=${LOKI_ALLOWED_PATHS:-""}                  # Empty = all paths allowed
 BLOCKED_COMMANDS=${LOKI_BLOCKED_COMMANDS:-"rm -rf /,dd if=,mkfs,:(){ :|:& };:"}
 
@@ -1454,7 +1454,13 @@ stop_enterprise_services() {
 # Exit 0 = ALLOW, Exit 1 = DENY, Exit 2 = REQUIRE_APPROVAL (logged but allowed for now)
 check_policy() {
     local enforcement_point="$1"
-    local context_json="${2:-{}}"
+    # Default to a valid empty-object JSON. Do NOT inline `${2:-{}}`: the
+    # closing brace of the parameter expansion eats the first `}` of the
+    # `{}` default, so a non-empty $2 like {"a":1} would pass through as
+    # {"a":1}} (invalid JSON -> check.js JSON.parse fails -> exit 1 DENY
+    # every iteration). Split the default assignment to avoid the footgun.
+    local context_json="${2:-}"
+    [ -z "$context_json" ] && context_json='{}'
 
     # Only check if policy files exist
     if [ ! -f ".loki/policies.json" ] && [ ! -f ".loki/policies.yaml" ]; then
@@ -8313,6 +8319,89 @@ enforce_mutation_integrity() {
     return 0
 }
 
+# ============================================================================
+# Semantic Test-Authenticity Gate (P1-3): wire tests/detect-semantic-test-problems.sh
+# as an OPT-IN completion gate. The detector catches the harder class of fake
+# tests that the regex detectors (gates 5+6) miss: assertions that look real but
+# verify nothing because the asserted value never flows through code under test
+# (literal-via-variable echo HIGH, mock-return echo MED, deleted assertions MED).
+#
+# ADVISORY-FIRST POSTURE (no-deadlock contract): this helper is invoked ONLY when
+# LOKI_GATE_SEMANTIC_TESTS=true (the elif guard at the completion-promise arm
+# short-circuits when off, so there is zero runtime cost on the default path).
+# When on, it runs the detector with --block-high (clean exit-code contract:
+# rc 2 iff a CRITICAL/HIGH finding exists). We surface ALL severities to a
+# findings file (advisory) and return nonzero ONLY on rc 2. Every other exit --
+# rc 0 (clean), rc 124 (timeout), detector absent, no test files, malformed
+# output -- returns 0 (pass/fall-through), so the autonomous loop can NEVER
+# deadlock on a clean run. Mirrors enforce_mock_integrity's invocation
+# (cd TARGET_DIR + LOKI_SCAN_DIR=TARGET_DIR + timeout), swapping --strict for
+# --block-high and deciding on the rc-2 contract instead of grepping stdout.
+# ============================================================================
+enforce_semantic_integrity() {
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local quality_dir="$loki_dir/quality"
+    mkdir -p "$quality_dir"
+    local findings_file="$quality_dir/semantic-findings.txt"
+    local detector="$SCRIPT_DIR/../tests/detect-semantic-test-problems.sh"
+    local gate_timeout="${LOKI_GATE_TIMEOUT:-300}"
+
+    if [ ! -f "$detector" ]; then
+        log_info "Semantic test gate: detector not found, skipping (inconclusive)"
+        rm -f "$findings_file" 2>/dev/null || true
+        return 0
+    fi
+
+    local output rc
+    # --block-high exits 2 iff CRITICAL/HIGH present; 0 otherwise (clean wrapper).
+    output=$(cd "${TARGET_DIR:-.}" && LOKI_SCAN_DIR="${TARGET_DIR:-.}" \
+        timeout "$gate_timeout" bash "$detector" --block-high 2>&1)
+    rc=$?
+
+    # timeout exit 124 -- inconclusive, never block on a hang (deny-filter)
+    if [ "$rc" -eq 124 ]; then
+        log_warn "Semantic test gate: detector timed out after ${gate_timeout}s -- inconclusive"
+        rm -f "$findings_file" 2>/dev/null || true
+        return 0
+    fi
+
+    if [ "$rc" -eq 2 ]; then
+        # rc 2 == one or more CRITICAL/HIGH findings. Persist per-finding text.
+        {
+            echo "# Semantic test-authenticity findings (CRITICAL/HIGH block this completion)"
+            echo "$output" | grep -E '\[(CRITICAL|HIGH|MEDIUM|LOW)\]' || true
+        } > "$findings_file"
+        log_warn "Semantic test gate: CRITICAL/HIGH fake-test problems detected -- BLOCK"
+        return 1
+    fi
+
+    # rc 0 (and any other non-2, non-124 code, e.g. a malformed run) -> PASS.
+    # Route any MED/LOW advisory findings to the injection file, else clear it.
+    local med_low
+    med_low=$(echo "$output" | grep -E '\[(MEDIUM|LOW)\]' || true)
+    if [ -n "$med_low" ]; then
+        {
+            echo "# Semantic test advisory findings (MED/LOW, non-blocking)"
+            echo "$med_low"
+        } > "$findings_file"
+    else
+        rm -f "$findings_file" 2>/dev/null || true
+    fi
+    log_info "Semantic test gate: PASS"
+    return 0
+}
+
+# P1-3 wrapper that runs the semantic gate and returns its exact rc, mirroring
+# _evidence_gate_and_surface so the completion-promise elif arm reads cleanly
+# (`! _semantic_gate_and_surface`). Returns nonzero ONLY when enforce_semantic_integrity
+# saw an rc-2 (CRITICAL/HIGH) result; all deny-filter cases already collapse to 0
+# inside enforce_semantic_integrity, so this never blocks a clean run.
+_semantic_gate_and_surface() {
+    local _rc=0
+    enforce_semantic_integrity || _rc=$?
+    return "$_rc"
+}
+
 # ============================================================================
 # 3-Reviewer Parallel Code Review (v5.35.0)
 # Specialist pool from skills/quality-gates.md with blind review
@@ -12248,6 +12337,23 @@ if d.get('blocked'):
         gate_failure_context="${gate_failure_context}FIX THESE ISSUES BEFORE PROCEEDING WITH NEW WORK."
     fi
 
+    # P1-3: surface specific semantic test-authenticity findings (which fake test,
+    # which line) when the opt-in gate (LOKI_GATE_SEMANTIC_TESTS) wrote them, so a
+    # block converges: the agent gets the exact files/lines to fix rather than a
+    # bare gate name. The file exists only when the gate ran AND found something
+    # (cleared on clean), so this is zero-cost on the default path and when off.
+    # Mirrors the static-analysis/test-results detail-surfacing above. Surfaced
+    # whether the run blocked (CRIT/HIGH) or only advised (MED/LOW): both inform
+    # the next iteration. Independent of gate-failures.txt presence (the
+    # completion-promise arm does not append a gate token).
+    if [ -f "${TARGET_DIR:-.}/.loki/quality/semantic-findings.txt" ]; then
+        local sem_findings
+        sem_findings=$(grep -E '\[(CRITICAL|HIGH|MEDIUM|LOW)\]' "${TARGET_DIR:-.}/.loki/quality/semantic-findings.txt" 2>/dev/null | head -20 || true)
+        if [ -n "$sem_findings" ]; then
+            gate_failure_context="${gate_failure_context} SEMANTIC TEST-AUTHENTICITY FINDINGS (fix the fake tests; an assertion must verify a value that flows through the code under test, not echo a literal back): ${sem_findings}"
+        fi
+    fi
+
     # P2-2: high-severity spec-assumption context. When DISCOVERY recorded any
     # high-severity assumption (the spec was ambiguous in a high-impact place),
     # surface it to the build agent so it implements with the gap in view (or
@@ -15347,6 +15453,20 @@ else:
                 log_warn "Completion claim rejected: assumption ledger gate found unresolved high-severity spec assumption(s)."
                 log_warn "  Details under .loki/council/assumption-block.json ; opt out with LOKI_ASSUMPTION_GATE=0"
                 # Fall through; keep iterating until high-sev assumptions resolve.
+            # P1-3: semantic test-authenticity gate (OPT-IN, default OFF). Catches
+            # fake tests that look real but verify nothing (literal-via-variable
+            # echo etc.) that the regex gates 5+6 miss. ADVISORY-FIRST: the arm is
+            # guarded by LOKI_GATE_SEMANTIC_TESTS=true, so by default it never runs
+            # (zero runtime cost, never blocks). When enabled it runs the detector
+            # with --block-high and rejects the completion ONLY on a CRITICAL/HIGH
+            # finding; clean / no-test-files / detector-absent / timeout / malformed
+            # all collapse to a pass inside _semantic_gate_and_surface, so the
+            # autonomous loop can never deadlock on a clean run. Mirrors the
+            # evidence / held-out / assumption arms above.
+            elif [ "$_completion_claimed" = 1 ] && [ "${LOKI_GATE_SEMANTIC_TESTS:-false}" = "true" ] && type _semantic_gate_and_surface &>/dev/null && ! _semantic_gate_and_surface; then
+                log_warn "Completion claim rejected: semantic test-authenticity gate found CRITICAL/HIGH fake-test problem(s)."
+                log_warn "  Details under .loki/quality/semantic-findings.txt ; opt-in gate -- disable with LOKI_GATE_SEMANTIC_TESTS=false"
+                # Fall through; keep iterating until the fake tests are fixed.
             elif [ "$_completion_claimed" = 1 ]; then
                 echo ""
                 if [ -n "$COMPLETION_PROMISE" ]; then

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.52.0"
+__version__ = "7.54.0"
 
 # Expose the control app for easy import
 try:

package/dashboard/server.py

@@ -3248,6 +3248,121 @@ async def get_audit_summary(days: int = 7):
     return audit.get_audit_summary(days=days)
 
 
+# Continuous compliance surface (P3-11).
+#
+# Exposes the agent audit chain's compliance posture as an always-available
+# live endpoint. There is NO background scheduler in this surface (that is
+# infra, out of scope): the report is regenerated from the CURRENT audit
+# state on every request, so the endpoint is "continuous" in the sense that
+# it always reflects live state -- never a stale cached snapshot.
+#
+# The report is produced by the authoritative Node compliance engine
+# (src/audit/index.js, the single source of truth for SOC2/ISO/GDPR control
+# mappings) via its `report` CLI shim, so the Python surface never
+# reimplements (and never drifts from) the mapping logic. The chain it reads
+# is the JS AGENT chain at <project>/.loki/audit/audit.jsonl -- a different
+# chain from the Python dashboard chain that /api/enterprise/audit serves
+# (the two are reconciled by the cross-link verifier, not merged), so this
+# endpoint deliberately does NOT gate on audit.is_audit_enabled() (that flag
+# governs the Python chain). When the agent chain has no entries the report
+# is returned honestly with totalAuditEntries == 0; no fabricated pass.
+_COMPLIANCE_TYPES = ("soc2", "iso27001", "gdpr")
+
+
+@app.get("/api/compliance", dependencies=[Depends(auth.require_scope("audit"))])
+def get_compliance_status(report_type: str = Query("soc2", alias="type")):
+    """Live compliance status for the active project's agent audit chain.
+
+    Auth/tenant scoping: requires the `audit` scope (same gate as the
+    /api/enterprise/audit family). The data is filesystem state scoped to
+    the active project via _get_loki_dir(), exactly like the other
+    .loki-backed read endpoints; there is no DB tenant_id on a JSONL file
+    to enforce against.
+
+    Query: ?type=soc2|iso27001|gdpr (default soc2).
+
+    Returns the compliance report JSON regenerated from CURRENT audit
+    state on every call. If no audit data has been recorded the report is
+    honestly empty (totalAuditEntries == 0), not a fabricated compliant
+    verdict. If the Node engine is unavailable, returns an honest
+    available:false payload (HTTP 200) rather than masquerading as "no
+    compliance".
+    """
+    if not _read_limiter.check("compliance"):
+        raise HTTPException(status_code=429, detail="Rate limit exceeded")
+    if report_type not in _COMPLIANCE_TYPES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Invalid type: {report_type}. Must be one of {list(_COMPLIANCE_TYPES)}",
+        )
+
+    import shutil
+
+    # The agent audit chain lives under <project>/.loki/audit; _get_loki_dir()
+    # returns the .loki dir, so the project root is its parent.
+    project_dir = str(_get_loki_dir().parent.resolve())
+    repo_root = _Path(__file__).resolve().parent.parent
+    index_js = repo_root / "src" / "audit" / "index.js"
+
+    node_bin = shutil.which("node")
+    if node_bin is None or not index_js.exists():
+        return {
+            "available": False,
+            "reason": (
+                "Node runtime not found"
+                if node_bin is None
+                else f"compliance engine not found at {index_js}"
+            ),
+            "reportType": report_type,
+            "projectDir": project_dir,
+            "report": None,
+        }
+
+    try:
+        proc = subprocess.run(
+            [node_bin, str(index_js), "report", report_type, project_dir],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return {
+            "available": False,
+            "reason": f"compliance engine invocation failed: {exc}",
+            "reportType": report_type,
+            "projectDir": project_dir,
+            "report": None,
+        }
+
+    if proc.returncode != 0:
+        return {
+            "available": False,
+            "reason": (proc.stderr or "compliance engine returned non-zero").strip()[:500],
+            "reportType": report_type,
+            "projectDir": project_dir,
+            "report": None,
+        }
+
+    try:
+        report = json.loads(proc.stdout.strip())
+    except json.JSONDecodeError:
+        return {
+            "available": False,
+            "reason": "compliance engine produced non-JSON output",
+            "reportType": report_type,
+            "projectDir": project_dir,
+            "report": None,
+        }
+
+    return {
+        "available": True,
+        "reportType": report_type,
+        "projectDir": project_dir,
+        "report": report,
+    }
+
+
 # =============================================================================
 # File-based Session Endpoints (reads from .loki/ flat files)
 # =============================================================================

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.52.0
+**Version:** v7.54.0
 
 ---
 
@@ -312,7 +312,6 @@ Loki Mode supports four active providers across three tiers, plus historical/upc
 | `codex`  | Active | Tier 3 (degraded) | Sequential only, no Task tool; aligned with `@openai/codex` v0.125+. |
 | `aider`  | Active | Tier 3 (degraded) | Sequential only; `ollama_chat/<model>` works for local models. |
 | `gemini` | DEPRECATED v7.5.18 | -- | Upstream Gemini CLI deprecated by Google. Runtime removed; `LOKI_PROVIDER=gemini` exits with migration message. |
-| `antigravity` | Coming soon | -- | Anthropic Antigravity CLI integration planned. |
 
 ### Configuration
 
@@ -396,7 +395,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.52.0 start ./my-spec.md
+  asklokesh/loki-mode:7.54.0 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var r6=Object.defineProperty;var t6=($)=>$;function i6($,Q){this[$]=t6.bind(null,Q)}var h=($,Q)=>{for(var Z in Q)r6($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:i6.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var K$=import.meta.require;var D1={};h(D1,{lokiDir:()=>P,homeLokiDir:()=>n$,findRepoRootForVersion:()=>o$,REPO_ROOT:()=>g});import{resolve as n,dirname as d$}from"path";import{fileURLToPath as e6}from"url";import{existsSync as P$}from"fs";import{homedir as $Q}from"os";function QQ(){let $=S1;for(let Q=0;Q<6;Q++){if(P$(n($,"VERSION"))&&P$(n($,"autonomy/run.sh")))return $;let Z=d$($);if(Z===$)break;$=Z}return n(S1,"..","..","..")}function o$($){let Q=$;for(let Z=0;Z<6;Z++){if(P$(n(Q,"VERSION"))&&P$(n(Q,"autonomy/run.sh")))return Q;let z=d$(Q);if(z===Q)break;Q=z}return n($,"..","..","..")}function P(){return process.env.LOKI_DIR??n(process.cwd(),".loki")}function n$(){return n($Q(),".loki")}var S1,g;var b=L(()=>{S1=d$(e6(import.meta.url));g=QQ()});import{readFileSync as ZQ}from"fs";import{resolve as zQ,dirname as XQ}from"path";import{fileURLToPath as KQ}from"url";function j$(){if($$!==null)return $$;let $="7.52.0";if(typeof $==="string"&&$.length>0)return $$=$,$$;try{let Q=XQ(KQ(import.meta.url)),Z=o$(Q);$$=ZQ(zQ(Z,"VERSION"),"utf-8").trim()}catch{$$="unknown"}return $$}var $$=null;var a$=L(()=>{b()});var b1={};h(b1,{runOrThrow:()=>qQ,run:()=>k,commandVersion:()=>WQ,commandExists:()=>f,ShellError:()=>s$});async function k($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,W]=await Promise.all([new Response(Z.stdout).text(),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:W}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function qQ($,Q={}){let Z=await k($,Q);if(Z.exitCode!==0)throw new s$(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=VQ($),Z=await k(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function VQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function WQ($,Q="--version"){if(!await f($))return null;let z=await k([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var s$;var d=L(()=>{s$=class s$ extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function a($){return JQ?"":$}var JQ,T,S,_,wZ,I,R,y,V;var c=L(()=>{JQ=(process.env.NO_COLOR??"").length>0;T=a("\x1B[0;31m"),S=a("\x1B[0;32m"),_=a("\x1B[1;33m"),wZ=a("\x1B[0;34m"),I=a("\x1B[0;36m"),R=a("\x1B[1m"),y=a("\x1B[2m"),V=a("\x1B[0m")});import{existsSync as wQ}from"fs";async function Q$(){if(G$!==void 0)return G$;let $="/opt/homebrew/bin/python3.12";if(wQ($))return G$=$,$;let Q=await f("python3.12");if(Q)return G$=Q,Q;let Z=await f("python3");return G$=Z,Z}async function Z$($,Q={}){let Z=await Q$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return k([Z,"-c",$],Q)}var G$;var q$=L(()=>{d()});var e1={};h(e1,{runStatus:()=>uQ});import{existsSync as v,readFileSync as W$,readdirSync as d1,statSync as o1}from"fs";import{resolve as C,basename as DQ}from"path";import{homedir as CQ}from"os";function n1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function a1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*k$/Q);if(X>k$)X=k$;let q=k$-X,K=S;if(z>=80)K=T;else if(z>=50)K=_;let W="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=n1($),U=n1(Q);return`  ${R}${Z}${V} ${K}[${W}]${V} ${z}% (${J} / ${U})`}async function hQ(){if(await f("jq"))return!0;return process.stdout.write(`${T}Error: jq is required but not installed.${V}
+var r6=Object.defineProperty;var t6=($)=>$;function i6($,Q){this[$]=t6.bind(null,Q)}var h=($,Q)=>{for(var Z in Q)r6($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:i6.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var K$=import.meta.require;var D1={};h(D1,{lokiDir:()=>P,homeLokiDir:()=>n$,findRepoRootForVersion:()=>o$,REPO_ROOT:()=>g});import{resolve as n,dirname as d$}from"path";import{fileURLToPath as e6}from"url";import{existsSync as P$}from"fs";import{homedir as $Q}from"os";function QQ(){let $=S1;for(let Q=0;Q<6;Q++){if(P$(n($,"VERSION"))&&P$(n($,"autonomy/run.sh")))return $;let Z=d$($);if(Z===$)break;$=Z}return n(S1,"..","..","..")}function o$($){let Q=$;for(let Z=0;Z<6;Z++){if(P$(n(Q,"VERSION"))&&P$(n(Q,"autonomy/run.sh")))return Q;let z=d$(Q);if(z===Q)break;Q=z}return n($,"..","..","..")}function P(){return process.env.LOKI_DIR??n(process.cwd(),".loki")}function n$(){return n($Q(),".loki")}var S1,g;var b=L(()=>{S1=d$(e6(import.meta.url));g=QQ()});import{readFileSync as ZQ}from"fs";import{resolve as zQ,dirname as XQ}from"path";import{fileURLToPath as KQ}from"url";function j$(){if($$!==null)return $$;let $="7.54.0";if(typeof $==="string"&&$.length>0)return $$=$,$$;try{let Q=XQ(KQ(import.meta.url)),Z=o$(Q);$$=ZQ(zQ(Z,"VERSION"),"utf-8").trim()}catch{$$="unknown"}return $$}var $$=null;var a$=L(()=>{b()});var b1={};h(b1,{runOrThrow:()=>qQ,run:()=>k,commandVersion:()=>WQ,commandExists:()=>f,ShellError:()=>s$});async function k($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,W]=await Promise.all([new Response(Z.stdout).text(),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:W}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function qQ($,Q={}){let Z=await k($,Q);if(Z.exitCode!==0)throw new s$(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=VQ($),Z=await k(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function VQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function WQ($,Q="--version"){if(!await f($))return null;let z=await k([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var s$;var d=L(()=>{s$=class s$ extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function a($){return JQ?"":$}var JQ,T,S,_,wZ,I,R,y,V;var c=L(()=>{JQ=(process.env.NO_COLOR??"").length>0;T=a("\x1B[0;31m"),S=a("\x1B[0;32m"),_=a("\x1B[1;33m"),wZ=a("\x1B[0;34m"),I=a("\x1B[0;36m"),R=a("\x1B[1m"),y=a("\x1B[2m"),V=a("\x1B[0m")});import{existsSync as wQ}from"fs";async function Q$(){if(G$!==void 0)return G$;let $="/opt/homebrew/bin/python3.12";if(wQ($))return G$=$,$;let Q=await f("python3.12");if(Q)return G$=Q,Q;let Z=await f("python3");return G$=Z,Z}async function Z$($,Q={}){let Z=await Q$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return k([Z,"-c",$],Q)}var G$;var q$=L(()=>{d()});var e1={};h(e1,{runStatus:()=>uQ});import{existsSync as v,readFileSync as W$,readdirSync as d1,statSync as o1}from"fs";import{resolve as C,basename as DQ}from"path";import{homedir as CQ}from"os";function n1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function a1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*k$/Q);if(X>k$)X=k$;let q=k$-X,K=S;if(z>=80)K=T;else if(z>=50)K=_;let W="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=n1($),U=n1(Q);return`  ${R}${Z}${V} ${K}[${W}]${V} ${z}% (${J} / ${U})`}async function hQ(){if(await f("jq"))return!0;return process.stdout.write(`${T}Error: jq is required but not installed.${V}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -790,4 +790,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write(s6),2}}l1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var KZ=await XZ(Bun.argv.slice(2));process.exit(KZ);
 
-//# debugId=D3609A2FE6BB9BAE64756E2164756E21
+//# debugId=45D73957F12E90DF64756E2164756E21

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '7.52.0'
+__version__ = '7.54.0'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.52.0",
+  "version": "7.54.0",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "7.52.0",
+  "version": "7.54.0",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",

package/skills/quality-gates.md

@@ -2,12 +2,14 @@
 
 **Never ship code without passing all quality gates.**
 
-## The 8 Quality Gates
+## The Quality Gates (8 default-on + 1 opt-in)
 
-Every gate below is wired into the orchestration loop (`autonomy/run.sh`) and
-blocks completion when it fails. The table lists exactly what each gate detects,
-what it does NOT detect (so you never over-trust a green gate), its opt-out flag,
-and its blocking behavior. Transcribe this list verbatim; do not recompute it.
+Every gate below is wired into the orchestration loop (`autonomy/run.sh`). The 8
+numbered gates are default-on and block completion when they fail; the opt-in
+gate (marked below) is default-OFF and runs only when its flag is set. The table
+lists exactly what each gate detects, what it does NOT detect (so you never
+over-trust a green gate), its opt-out flag, and its blocking behavior. Transcribe
+this list verbatim; do not recompute it.
 
 | # | Gate | Detects | Does NOT detect | Blocking | Opt-out flag |
 |---|------|---------|-----------------|----------|--------------|
@@ -19,6 +21,7 @@ and its blocking behavior. Transcribe this list verbatim; do not recompute it.
 | 6 | Test Mutation Detector | Assertion-value churn alongside implementation changes (test-fitting), low assertion density (`tests/detect-test-mutations.sh`); HIGH blocks | Logically-correct-but-weak assertions | Yes (HIGH blocks) | `LOKI_GATE_MUTATION=false` |
 | 7 | Documentation Coverage | README presence, docs freshness within 10 commits, API docs for exported symbols in packages | Whether the docs are accurate or useful | Yes | `LOKI_GATE_DOC_COVERAGE=false` |
 | 8 | Magic Modules Debate | Spec-vs-implementation debate findings on generated Magic Modules; BLOCK-severity findings block | Issues outside the Magic Modules debate scope | Yes (BLOCK severity) | `LOKI_GATE_MAGIC_DEBATE=false` |
+| 9 (opt-in, default OFF) | Semantic Test-Authenticity | Fake tests that look real but verify nothing (literal-via-variable echo, mock-return echo, deleted assertions) that gates 5+6 miss (`tests/detect-semantic-test-problems.sh --block-high`); CRITICAL/HIGH block | Deep dataflow, legitimate computed-literal assertions, Python/shell tests (JS/TS only); MED/LOW are advisory | Only when enabled, and only on CRITICAL/HIGH; runs solely on a completion claim | Opt-IN: `LOKI_GATE_SEMANTIC_TESTS=true` to enable (default off = not invoked, never blocks) |
 
 **Severity-based blocking** ties the review gates together: any Critical or High
 finding blocks completion. Medium, Low, and cosmetic findings are advisory and

package/src/audit/compliance-scheduler.js

@@ -0,0 +1,287 @@
+'use strict';
+
+/**
+ * Compliance snapshot scheduler (lightweight helper, NOT a daemon).
+ *
+ * v7.53.0 shipped a live GET /api/compliance endpoint that regenerates a
+ * compliance report on demand. This module is the remaining P3-11 piece:
+ * OPTIONAL scheduled/continuous generation so a compliance snapshot is
+ * periodically PERSISTED to disk. That gives two things a live dashboard
+ * call cannot:
+ *
+ *   1. Trend / history: a series of timestamped snapshots over time.
+ *   2. Air-gapped audit evidence: durable, self-contained proof on disk
+ *      without anyone making a live API call.
+ *
+ * It is deliberately NOT a background process. The gate function
+ * (maybeGenerateSnapshot) is meant to be invoked opportunistically (for
+ * example once per autonomous run) and self-rate-limits: it only writes a
+ * new snapshot when the configured interval has elapsed since the last one.
+ * That makes it "continuous" when enabled without needing a daemon or any
+ * always-running loop.
+ *
+ * HONESTY: every snapshot is generated from the REAL current audit chain
+ * (AuditLog.readEntries) and the REAL tamper-evidence verdict
+ * (AuditLog.verifyChain), exactly like index.js getReport. An empty chain
+ * yields an honest empty snapshot (totalAuditEntries: 0), never a
+ * fabricated "compliant" verdict.
+ *
+ * DEFAULT DISABLED: with no configured interval (LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS
+ * unset or 0), maybeGenerateSnapshot is a no-op and adds zero behavior for
+ * existing users.
+ *
+ * NOT YET AUTO-INVOKED: this wave ships the tested helper only. It is not
+ * wired into run.sh or any live loop here (that is integration, owned by the
+ * run.sh owners). See "How to invoke" below for the intended call site.
+ *
+ * How to invoke (intended integration, not yet wired):
+ *   var scheduler = require('./src/audit/compliance-scheduler');
+ *   // Once per run, after init:
+ *   scheduler.maybeGenerateSnapshot({ projectDir: process.cwd() });
+ *   // Reads LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS; no-op unless elapsed.
+ */
+
+var fs = require('fs');
+var path = require('path');
+var { AuditLog } = require('./log');
+var compliance = require('./compliance');
+
+var ENV_INTERVAL = 'LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS';
+var SNAPSHOT_DIRNAME = 'compliance-snapshots';
+var MARKER_FILENAME = 'last-snapshot.json';
+var MS_PER_HOUR = 3600 * 1000;
+
+/**
+ * Parse a configured interval (hours) into a number. Returns 0 (disabled)
+ * for unset, empty, non-numeric, negative, or NaN values. 0 means the
+ * scheduler is disabled and maybeGenerateSnapshot is a no-op.
+ *
+ * @param {*} raw - Raw value (typically process.env.LOKI_COMPLIANCE_SNAPSHOT_INTERVAL_HOURS)
+ * @returns {number} Interval in hours, or 0 if disabled / invalid.
+ */
+function parseIntervalHours(raw) {
+  if (raw === undefined || raw === null || raw === '') return 0;
+  var n = Number(raw);
+  if (!isFinite(n) || n <= 0) return 0;
+  return n;
+}
+
+/**
+ * Resolve the snapshot directory for a project: <projectDir>/.loki/audit/compliance-snapshots.
+ */
+function snapshotDir(projectDir) {
+  return path.join(projectDir || process.cwd(), '.loki', 'audit', SNAPSHOT_DIRNAME);
+}
+
+/**
+ * Resolve the rate-limit marker file path.
+ */
+function markerPath(projectDir) {
+  return path.join(snapshotDir(projectDir), MARKER_FILENAME);
+}
+
+/**
+ * Read the last-generated timestamp (ms) from the marker file. Returns null
+ * if no marker exists or it is unreadable / malformed (treated as "never
+ * generated" so the next call generates).
+ */
+function readLastGeneratedAtMs(projectDir) {
+  var p = markerPath(projectDir);
+  try {
+    if (!fs.existsSync(p)) return null;
+    var raw = fs.readFileSync(p, 'utf8');
+    var obj = JSON.parse(raw);
+    var ms = Number(obj && obj.lastGeneratedAtMs);
+    if (!isFinite(ms)) return null;
+    return ms;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Build a compliance snapshot from the REAL audit chain for a project.
+ *
+ * Bundles all three report types (soc2, iso27001, gdpr), each generated
+ * from the live audit entries, plus the single shared tamper-evidence
+ * verdict. This mirrors index.js getReport's honesty: the chainIntegrity
+ * verdict comes from verifyChain(), and a verification error is recorded
+ * as a valid:false verdict rather than being allowed to throw or fabricate
+ * a pass. An empty chain produces totalAuditEntries: 0 honestly.
+ *
+ * This does NOT use the index.js singleton; it reads the chain directly so
+ * it is self-contained and free of shared-state coupling.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir - Project root whose .loki/audit chain is read.
+ * @param {object} [args.reportOpts] - Options forwarded to the generators (projectName, period, etc.)
+ * @param {number} [args.nowMs] - Clock for generatedAt (defaults to Date.now()).
+ * @returns {object} The snapshot object.
+ */
+function buildSnapshot(args) {
+  args = args || {};
+  var projectDir = args.projectDir || process.cwd();
+  var reportOpts = args.reportOpts || {};
+  var nowMs = (typeof args.nowMs === 'number') ? args.nowMs : Date.now();
+
+  var log = new AuditLog({ projectDir: projectDir });
+  var entries;
+  try {
+    entries = log.readEntries();
+  } catch (e) {
+    entries = [];
+  }
+
+  // Real tamper-evidence verdict. Do not let a verification error fabricate
+  // a pass: capture it honestly as a valid:false verdict instead.
+  var chainIntegrity;
+  try {
+    chainIntegrity = log.verifyChain();
+  } catch (e) {
+    chainIntegrity = {
+      valid: false,
+      entries: entries.length,
+      brokenAt: null,
+      error: 'chain verification failed: ' + String((e && e.message) || e),
+    };
+  }
+
+  try { log.destroy(); } catch (_) { /* noop */ }
+
+  var soc2 = compliance.generateSoc2Report(entries, reportOpts);
+  soc2.chainIntegrity = chainIntegrity;
+  var iso27001 = compliance.generateIso27001Report(entries, reportOpts);
+  iso27001.chainIntegrity = chainIntegrity;
+  var gdpr = compliance.generateGdprReport(entries, reportOpts);
+  gdpr.chainIntegrity = chainIntegrity;
+
+  return {
+    snapshotVersion: 1,
+    generatedAt: new Date(nowMs).toISOString(),
+    projectName: reportOpts.projectName || 'Loki Mode',
+    totalAuditEntries: entries.length,
+    chainIntegrity: chainIntegrity,
+    reports: {
+      soc2: soc2,
+      iso27001: iso27001,
+      gdpr: gdpr,
+    },
+  };
+}
+
+/**
+ * Build a filesystem-safe snapshot filename from an ISO timestamp. ISO
+ * strings contain colons and dots which are fine on macOS/Linux but are
+ * sanitized to hyphens anyway for portability.
+ */
+function snapshotFilename(isoTimestamp) {
+  var safe = String(isoTimestamp).replace(/[:.]/g, '-');
+  return 'compliance-' + safe + '.json';
+}
+
+/**
+ * Persist a snapshot to disk and update the rate-limit marker.
+ *
+ * Writes <snapshotDir>/compliance-<timestamp>.json and updates
+ * <snapshotDir>/last-snapshot.json with the generation clock so the next
+ * gate decision reads the same clock that produced the snapshot.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir - Project root.
+ * @param {object} args.snapshot - Snapshot object (from buildSnapshot).
+ * @param {number} args.nowMs - Generation clock in ms (stored in the marker).
+ * @returns {string} The absolute path of the written snapshot file.
+ */
+function persistSnapshot(args) {
+  var projectDir = args.projectDir || process.cwd();
+  var snapshot = args.snapshot;
+  var nowMs = args.nowMs;
+  var dir = snapshotDir(projectDir);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  var file = path.join(dir, snapshotFilename(snapshot.generatedAt));
+  fs.writeFileSync(file, JSON.stringify(snapshot, null, 2), 'utf8');
+  fs.writeFileSync(
+    markerPath(projectDir),
+    JSON.stringify({ lastGeneratedAtMs: nowMs, lastSnapshotFile: path.basename(file) }, null, 2),
+    'utf8'
+  );
+  return file;
+}
+
+/**
+ * Opportunistic, self-rate-limiting snapshot generation.
+ *
+ * Decides whether to generate a snapshot now based on the configured
+ * interval and the persisted last-generated timestamp:
+ *
+ *   - Interval 0 / unset (default) -> no-op, reason 'disabled'.
+ *   - No prior snapshot and interval > 0 -> generate (first run).
+ *   - now - lastGeneratedAt >= interval -> generate.
+ *   - Otherwise -> no-op, reason 'not-elapsed'.
+ *
+ * Both the interval and the clock are injectable via opts so callers (and
+ * tests) can control them; env is the fallback for the interval and
+ * Date.now() the fallback for the clock.
+ *
+ * Return contract:
+ *   { generated: true, path: <file>, report: <snapshot>, intervalHours }
+ *   { generated: false, reason: 'disabled', intervalHours: 0 }
+ *   { generated: false, reason: 'not-elapsed', intervalHours, nextEligibleAtMs }
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir] - Project root (default process.cwd()).
+ * @param {number} [opts.intervalHours] - Interval override; falls back to env.
+ * @param {number} [opts.now] - Current time in ms; falls back to Date.now().
+ * @param {object} [opts.reportOpts] - Options forwarded to report generators.
+ * @returns {object} Result per the return contract above.
+ */
+function maybeGenerateSnapshot(opts) {
+  opts = opts || {};
+  var projectDir = opts.projectDir || process.cwd();
+  var intervalHours = (typeof opts.intervalHours === 'number')
+    ? parseIntervalHours(opts.intervalHours)
+    : parseIntervalHours(process.env[ENV_INTERVAL]);
+  var now = (typeof opts.now === 'number') ? opts.now : Date.now();
+
+  if (intervalHours <= 0) {
+    return { generated: false, reason: 'disabled', intervalHours: 0 };
+  }
+
+  var lastMs = readLastGeneratedAtMs(projectDir);
+  var intervalMs = intervalHours * MS_PER_HOUR;
+
+  if (lastMs !== null && (now - lastMs) < intervalMs) {
+    return {
+      generated: false,
+      reason: 'not-elapsed',
+      intervalHours: intervalHours,
+      nextEligibleAtMs: lastMs + intervalMs,
+    };
+  }
+
+  var snapshot = buildSnapshot({
+    projectDir: projectDir,
+    reportOpts: opts.reportOpts,
+    nowMs: now,
+  });
+  var file = persistSnapshot({ projectDir: projectDir, snapshot: snapshot, nowMs: now });
+
+  return {
+    generated: true,
+    path: file,
+    report: snapshot,
+    intervalHours: intervalHours,
+  };
+}
+
+module.exports = {
+  maybeGenerateSnapshot: maybeGenerateSnapshot,
+  buildSnapshot: buildSnapshot,
+  persistSnapshot: persistSnapshot,
+  parseIntervalHours: parseIntervalHours,
+  snapshotDir: snapshotDir,
+  markerPath: markerPath,
+  ENV_INTERVAL: ENV_INTERVAL,
+};

package/src/audit/index.js

@@ -83,6 +83,84 @@ function exportReport(type, opts) {
   return compliance.exportReportJson(report);
 }
 
+/**
+ * Generate a compliance report as a plain object, with the agent-chain
+ * tamper-evidence verdict folded in.
+ *
+ * This is the object form intended for surfaces (e.g. the dashboard
+ * /api/compliance endpoint) that need the report as data rather than a
+ * pre-serialized string. It always reflects the REAL audit chain:
+ *
+ *   - The report body is generated from the live audit entries
+ *     (`_log.readEntries()`), never fabricated.
+ *   - `chainIntegrity` is populated from `verifyChain()` so the report
+ *     carries the true tamper-evidence state of the underlying chain.
+ *     For the SOC2 report this fills the `chainIntegrity: null` slot the
+ *     generator leaves for the caller; for the other report types it is
+ *     attached under the same key for a uniform surface contract.
+ *
+ * When the chain has no entries the report is still returned honestly
+ * with `totalAuditEntries: 0` (an empty-but-valid report), never a
+ * fabricated "compliant" verdict.
+ *
+ * @param {string} type - 'soc2', 'iso27001', or 'gdpr'
+ * @param {object} [opts] - Report options (projectName, period, etc.)
+ * @returns {object} The compliance report object with chainIntegrity set.
+ */
+function getReport(type, opts) {
+  if (!_initialized) init();
+  var report = generateReport(type, opts);
+  // Fold the real tamper-evidence verdict into the report. Do not let a
+  // verification error fabricate a pass: capture it honestly instead.
+  try {
+    report.chainIntegrity = _log.verifyChain();
+  } catch (e) {
+    report.chainIntegrity = {
+      valid: false,
+      entries: report.totalAuditEntries || 0,
+      brokenAt: null,
+      error: 'chain verification failed: ' + String((e && e.message) || e),
+    };
+  }
+  return report;
+}
+
+/**
+ * CLI shim so a non-Node surface (e.g. the Python dashboard) can fetch a
+ * compliance report for a given project directory as JSON on stdout.
+ *
+ * This mirrors the inverse of dashboard/audit.py's `_unified_cli()`
+ * (which lets the Node-side unified verifier read the Python chain).
+ *
+ * Invoked as:
+ *   node src/audit/index.js report <type> <projectDir>
+ *
+ * <type> is one of soc2 | iso27001 | gdpr. <projectDir> is the project
+ * root whose .loki/audit/audit.jsonl chain is read. Prints a single JSON
+ * object to stdout. Returns exit 0 on success, 2 on usage error.
+ *
+ * The report is generated from the REAL chain; an absent/empty chain
+ * yields an honest empty report (totalAuditEntries: 0), not a fake pass.
+ */
+function _cli(argv) {
+  var args = argv || [];
+  var VALID_TYPES = { soc2: true, iso27001: true, gdpr: true };
+  if (args.length < 2 || args[0] !== 'report' || !VALID_TYPES[args[1]]) {
+    process.stdout.write(JSON.stringify({
+      error: 'usage: index.js report {soc2|iso27001|gdpr} <projectDir>',
+    }) + '\n');
+    return 2;
+  }
+  var type = args[1];
+  var projectDir = args[2] || process.cwd();
+  destroy();
+  init(projectDir);
+  var report = getReport(type);
+  destroy();
+  process.stdout.write(JSON.stringify(report) + '\n');
+  return 0;
+}
+
 /**
  * Check if a provider is allowed by data residency policy.
  */
@@ -167,6 +245,7 @@ module.exports = {
   verifyChain: verifyChain,
   generateReport: generateReport,
   exportReport: exportReport,
+  getReport: getReport,
   checkProvider: checkProvider,
   isAirGapped: isAirGapped,
   readEntries: readEntries,
@@ -177,3 +256,8 @@ module.exports = {
   verifyUnified: verifyUnified,
   writeWitness: writeWitness,
 };
+
+// CLI entry point: `node src/audit/index.js report <type> <projectDir>`.
+if (require.main === module) {
+  process.exit(_cli(process.argv.slice(2)));
+}