loki-mode 7.49.0 → 7.51.0

package/mcp/__init__.py

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

package/mcp/lsp_proxy.py

@@ -1304,6 +1304,180 @@ async def lsp_find_definition_by_name(symbol: str,
 # MAIN
 # ============================================================
 
+# ============================================================
+# DIAGNOSTICS WRITER (P1-5 quality gate)
+# ============================================================
+#
+# The LSP-diagnostics quality gate (loki-ts/src/runner/quality_gates.ts,
+# runLSPDiagnostics) READS <lokiDir>/quality/lsp-diagnostics.json but nothing
+# wrote it -- the gate was inert. This is the WRITER, invoked the same way on
+# both routes (Bun gate calls `python3 -m mcp.lsp_proxy --write-diagnostics`;
+# the bash route, when wired by the run.sh owner, calls the identical command),
+# so a single program produces byte-identical output for both. NO TS/bash
+# re-implementation of the aggregation -- that is the whole point of putting it
+# here.
+#
+# It enumerates the changed files itself (HEAD~1 -> --cached -> ls-files,
+# mirroring runStaticAnalysis's chain in quality_gates.ts so file selection
+# cannot diverge from the sibling static-analysis gate), queries each
+# supported file via the SAME in-process LSP client cache (_get_or_spawn_client,
+# one process for all files -- not python3-per-file), aggregates, and writes
+# the minimal deterministic shape the gate consumes.
+#
+# HONESTY (never fabricate a clean verdict from absence): when NO supported
+# language server is on PATH, or NO changed file maps to an available server,
+# the writer writes NO artifact and removes any stale one. The gate's existing
+# absence path then fires ("gate did not run") instead of a manufactured
+# "0 errors, 0 warnings" clean verdict. Likewise on any unrecoverable error
+# the writer leaves no artifact.
+#
+# DETERMINISM: the artifact carries ONLY the fields the gate reads
+# (count_errors, count_warnings, diagnostics[].severity/.message/.file).
+# Non-deterministic proxy fields (elapsed_ms, ranges, source) are dropped, and
+# diagnostics are sorted stably (file, severity, message) so the same inputs
+# always serialize byte-identically across runs and routes.
+
+_DIAG_ARTIFACT_REL = os.path.join('quality', 'lsp-diagnostics.json')
+
+
+def _writer_loki_dir() -> str:
+    """Resolve the .loki dir the artifact is written under. Honors LOKI_DIR
+    (matching loki-ts/src/util/paths.ts lokiDir()), else <cwd>/.loki."""
+    env = os.environ.get('LOKI_DIR')
+    if env:
+        return env
+    return os.path.join(os.getcwd(), '.loki')
+
+
+def _writer_changed_files(root: str) -> List[str]:
+    """Return changed files relative to `root`, mirroring the HEAD~1 ->
+    --cached -> ls-files chain in runStaticAnalysis (quality_gates.ts). An
+    empty-but-successful `git diff HEAD~1 HEAD` is honored as "no changes
+    this iteration" and does NOT fall through to ls-files (parity with the
+    tryGit null-vs-empty distinction in the TS gate)."""
+    def _try_git(git_args: List[str]) -> Optional[str]:
+        try:
+            proc = subprocess.run(
+                ['git', '-C', root, *git_args],
+                capture_output=True, text=True, timeout=30,
+            )
+        except (OSError, subprocess.SubprocessError):
+            return None
+        if proc.returncode != 0:
+            return None
+        return proc.stdout
+
+    raw: str
+    head_tilde = _try_git(['diff', '--name-only', 'HEAD~1', 'HEAD'])
+    if head_tilde is not None:
+        raw = head_tilde
+    else:
+        cached = _try_git(['diff', '--name-only', '--cached'])
+        if cached is not None and cached.strip():
+            raw = cached
+        else:
+            ls_files = _try_git(['ls-files'])
+            raw = ls_files if (ls_files is not None and ls_files.strip()) else ''
+    return [line.strip() for line in raw.splitlines() if line.strip()]
+
+
+def write_diagnostics_artifact(root: Optional[str] = None,
+                               loki_dir: Optional[str] = None) -> Dict[str, Any]:
+    """Enumerate changed files, query LSP diagnostics per supported file via
+    the shared in-process client cache, aggregate, and atomically write the
+    gate artifact. Returns a status dict (also printed by --write-diagnostics).
+
+    Writes NO artifact (and removes a stale one) when there is nothing real to
+    measure -- no detected server, or no changed file maps to a detected
+    server -- so the gate's absence path fires honestly instead of a fabricated
+    clean verdict."""
+    root = root or os.getcwd()
+    loki_dir = loki_dir or _writer_loki_dir()
+    artifact_path = os.path.join(loki_dir, _DIAG_ARTIFACT_REL)
+
+    def _remove_stale() -> None:
+        try:
+            if os.path.isfile(artifact_path):
+                os.remove(artifact_path)
+        except OSError:
+            pass
+
+    detected = _detect_lsps()
+    if not detected:
+        _remove_stale()
+        return {'measured': False, 'reason': 'no-language-server-on-path',
+                'wrote_artifact': False}
+
+    changed_rel = _writer_changed_files(root)
+    # Keep only files whose language has a detected server AND that exist on
+    # disk (skip deleted/renamed diff entries).
+    targets: List[str] = []
+    for rel in changed_rel:
+        abs_path = rel if os.path.isabs(rel) else os.path.join(root, rel)
+        if not os.path.isfile(abs_path):
+            continue
+        lang = _suffix_to_language(abs_path)
+        if lang is None or lang not in detected:
+            continue
+        targets.append(abs_path)
+
+    if not targets:
+        _remove_stale()
+        return {'measured': False, 'reason': 'no-changed-file-with-detected-server',
+                'wrote_artifact': False,
+                'detected': sorted(detected.keys())}
+
+    all_diags: List[Dict[str, Any]] = []
+    queried = 0
+    for abs_path in targets:
+        try:
+            raw = _lsp_get_diagnostics_blocking(abs_path)
+            parsed = json.loads(raw)
+        except (OSError, ValueError):
+            continue
+        if 'error' in parsed:
+            # Server present in detection but failed for this file (spawn
+            # failure, unsupported, etc.). Skip it -- do NOT count it clean.
+            continue
+        queried += 1
+        for d in parsed.get('diagnostics', []) or []:
+            sev = d.get('severity')
+            if not isinstance(sev, int):
+                continue
+            all_diags.append({
+                'file': abs_path,
+                'severity': sev,
+                'message': str(d.get('message', '')),
+            })
+
+    if queried == 0:
+        # Every detected-server file failed to produce a usable result. We
+        # measured nothing real -- do not fabricate a clean artifact.
+        _remove_stale()
+        return {'measured': False, 'reason': 'no-file-yielded-diagnostics',
+                'wrote_artifact': False, 'detected': sorted(detected.keys())}
+
+    # Stable sort so the same inputs serialize identically across runs/routes.
+    all_diags.sort(key=lambda d: (d['file'], d['severity'], d['message']))
+    count_errors = sum(1 for d in all_diags if d['severity'] == 1)
+    count_warnings = sum(1 for d in all_diags if d['severity'] == 2)
+    artifact = {
+        'count_errors': count_errors,
+        'count_warnings': count_warnings,
+        'diagnostics': all_diags,
+    }
+
+    os.makedirs(os.path.dirname(artifact_path), exist_ok=True)
+    body = json.dumps(artifact, indent=2, sort_keys=True) + '\n'
+    tmp_path = f'{artifact_path}.tmp.{os.getpid()}'
+    with open(tmp_path, 'w', encoding='utf-8') as fh:
+        fh.write(body)
+    os.replace(tmp_path, artifact_path)
+    return {'measured': True, 'wrote_artifact': True, 'path': artifact_path,
+            'files_queried': queried, 'count_errors': count_errors,
+            'count_warnings': count_warnings}
+
+
 def main() -> None:
     import argparse
     parser = argparse.ArgumentParser(
@@ -1317,7 +1491,36 @@ def main() -> None:
         '--port', type=int, default=8422,
         help='Port for HTTP transport (default: 8422).',
     )
+    parser.add_argument(
+        '--write-diagnostics', action='store_true',
+        help='One-shot: enumerate changed files, query LSP diagnostics for '
+             'each supported file, and write the quality-gate artifact at '
+             '<LOKI_DIR>/quality/lsp-diagnostics.json. Writes nothing when no '
+             'language server is available (the gate then reports "did not '
+             'run"). Used by the LSP-diagnostics quality gate on both routes.',
+    )
+    parser.add_argument(
+        '--root', default=None,
+        help='Project root to enumerate changed files in (default: cwd). The '
+             'caller MUST pass the TARGET project dir here, not the loki '
+             'install dir -- the install dir is only the import path for '
+             '`-m mcp.lsp_proxy`.',
+    )
     args = parser.parse_args()
+
+    if args.write_diagnostics:
+        # One-shot writer mode -- no MCP server, no event loop. Always cleans
+        # up any spawned LSP clients before exit. `--root` is the TARGET
+        # project (where the diff lives); it is independent of the process cwd
+        # (which the caller may set to the install dir so `-m mcp.lsp_proxy`
+        # imports).
+        try:
+            status = write_diagnostics_artifact(root=args.root)
+        finally:
+            _cleanup_all_clients()
+        print(json.dumps(status))
+        return
+
     # SIGTERM handler so docker stop / supervisord stop triggers cleanup
     # symmetrically to atexit. Re-raises via default handler so the
     # process actually exits.

package/mcp/tests/test_lsp_proxy.py

@@ -373,5 +373,174 @@ class LSPClientShutdownTests(unittest.TestCase):
         fake_proc.kill.assert_called()
 
 
+class DiagnosticsWriterTests(unittest.TestCase):
+    """P1-5: the diagnostics WRITER that feeds the LSP-diagnostics quality
+    gate (loki-ts/src/runner/quality_gates.ts runLSPDiagnostics). Proves
+    non-vacuity (real severity-1 diagnostics -> blocking artifact) at the
+    recording/aggregation layer, and the no-false-fire honesty paths (no
+    server / no measurable file -> NO artifact, so the gate's absence path
+    fires instead of a fabricated clean verdict)."""
+
+    def setUp(self):
+        self.lp = _import_lsp_proxy()
+        self.lp._reset_detection_cache()
+
+    def _make_repo(self, files):
+        """Create a tmp dir with the given {relpath: contents} and return it."""
+        d = tempfile.mkdtemp(prefix='loki-lsp-writer-')
+        for rel, body in files.items():
+            p = os.path.join(d, rel)
+            os.makedirs(os.path.dirname(p), exist_ok=True)
+            with open(p, 'w', encoding='utf-8') as fh:
+                fh.write(body)
+        return d
+
+    def test_no_server_writes_no_artifact(self):
+        """No detected language server -> measured:false, no artifact. The
+        gate must then report 'did not run', never a clean verdict."""
+        root = self._make_repo({'a.ts': 'const x = 1;\n'})
+        loki = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        with mock.patch.object(self.lp, '_detect_lsps', return_value={}):
+            status = self.lp.write_diagnostics_artifact(root=root, loki_dir=loki)
+        self.assertFalse(status['measured'])
+        self.assertFalse(status['wrote_artifact'])
+        self.assertFalse(os.path.isfile(
+            os.path.join(loki, 'quality', 'lsp-diagnostics.json')))
+
+    def test_server_present_but_no_matching_changed_file(self):
+        """Server detected for rust, but the changed file is .ts -> nothing
+        real to measure -> no artifact."""
+        root = self._make_repo({'a.ts': 'const x = 1;\n'})
+        loki = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        with mock.patch.object(self.lp, '_detect_lsps',
+                               return_value={'rust': '/usr/bin/rust-analyzer'}), \
+             mock.patch.object(self.lp, '_writer_changed_files',
+                               return_value=['a.ts']):
+            status = self.lp.write_diagnostics_artifact(root=root, loki_dir=loki)
+        self.assertFalse(status['measured'])
+        self.assertEqual(status['reason'], 'no-changed-file-with-detected-server')
+        self.assertFalse(os.path.isfile(
+            os.path.join(loki, 'quality', 'lsp-diagnostics.json')))
+
+    def test_real_error_recorded_and_blocks(self):
+        """NON-VACUITY: a severity-1 diagnostic from the per-file LSP query is
+        recorded into the artifact with count_errors>0 -- the exact shape the
+        gate blocks on. Diagnostics source is mocked at the proxy boundary so
+        this exercises the writer's enumeration + aggregation + serialization
+        WITHOUT fabricating a verdict (the gate still independently reads the
+        file)."""
+        root = self._make_repo({'src/main.py': 'x: int = "nope"\n'})
+        loki = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        fake = json.dumps({
+            'diagnostics': [
+                {'severity': 1, 'message': 'Type error', 'range': {}, 'source': 'x'},
+                {'severity': 2, 'message': 'Unused', 'range': {}},
+                {'severity': 3, 'message': 'Info note'},
+            ],
+            'count_errors': 1, 'count_warnings': 1,
+            'language': 'python', 'elapsed_ms': 123.4,
+        })
+        with mock.patch.object(self.lp, '_detect_lsps',
+                               return_value={'python': '/usr/bin/pyright'}), \
+             mock.patch.object(self.lp, '_writer_changed_files',
+                               return_value=['src/main.py']), \
+             mock.patch.object(self.lp, '_lsp_get_diagnostics_blocking',
+                               return_value=fake):
+            status = self.lp.write_diagnostics_artifact(root=root, loki_dir=loki)
+        self.assertTrue(status['measured'])
+        self.assertTrue(status['wrote_artifact'])
+        self.assertEqual(status['count_errors'], 1)
+        path = os.path.join(loki, 'quality', 'lsp-diagnostics.json')
+        self.assertTrue(os.path.isfile(path))
+        with open(path, encoding='utf-8') as fh:
+            artifact = json.load(fh)
+        self.assertEqual(artifact['count_errors'], 1)
+        self.assertEqual(artifact['count_warnings'], 1)
+        # Minimal deterministic shape: only severity/message/file survive;
+        # elapsed_ms / range / source are stripped.
+        self.assertEqual(len(artifact['diagnostics']), 3)
+        for d in artifact['diagnostics']:
+            self.assertEqual(set(d.keys()), {'file', 'severity', 'message'})
+        self.assertNotIn('elapsed_ms', artifact)
+
+    def test_per_file_lsp_error_does_not_count_clean(self):
+        """A detected server that returns {'error':...} for the only changed
+        file means we measured nothing -> no artifact (NOT a fabricated
+        clean verdict)."""
+        root = self._make_repo({'src/main.py': 'x = 1\n'})
+        loki = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        with mock.patch.object(self.lp, '_detect_lsps',
+                               return_value={'python': '/usr/bin/pyright'}), \
+             mock.patch.object(self.lp, '_writer_changed_files',
+                               return_value=['src/main.py']), \
+             mock.patch.object(self.lp, '_lsp_get_diagnostics_blocking',
+                               return_value=json.dumps({'error': 'spawn failed'})):
+            status = self.lp.write_diagnostics_artifact(root=root, loki_dir=loki)
+        self.assertFalse(status['measured'])
+        self.assertEqual(status['reason'], 'no-file-yielded-diagnostics')
+        self.assertFalse(os.path.isfile(
+            os.path.join(loki, 'quality', 'lsp-diagnostics.json')))
+
+    def test_clean_file_writes_zero_artifact(self):
+        """A measured file with no diagnostics writes a real 0/0 artifact --
+        this is a MEASURED clean result (we queried a live server), distinct
+        from the absence path."""
+        root = self._make_repo({'src/main.py': 'x = 1\n'})
+        loki = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        with mock.patch.object(self.lp, '_detect_lsps',
+                               return_value={'python': '/usr/bin/pyright'}), \
+             mock.patch.object(self.lp, '_writer_changed_files',
+                               return_value=['src/main.py']), \
+             mock.patch.object(self.lp, '_lsp_get_diagnostics_blocking',
+                               return_value=json.dumps({
+                                   'diagnostics': [], 'count_errors': 0,
+                                   'count_warnings': 0})):
+            status = self.lp.write_diagnostics_artifact(root=root, loki_dir=loki)
+        self.assertTrue(status['measured'])
+        path = os.path.join(loki, 'quality', 'lsp-diagnostics.json')
+        with open(path, encoding='utf-8') as fh:
+            artifact = json.load(fh)
+        self.assertEqual(artifact['count_errors'], 0)
+        self.assertEqual(artifact['count_warnings'], 0)
+        self.assertEqual(artifact['diagnostics'], [])
+
+    def test_stale_artifact_removed_when_unmeasured(self):
+        """A previously-written artifact must be removed when a later run
+        measures nothing, so last iteration's errors cannot block forever."""
+        root = self._make_repo({'a.ts': 'const x = 1;\n'})
+        loki = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        qdir = os.path.join(loki, 'quality')
+        os.makedirs(qdir, exist_ok=True)
+        stale = os.path.join(qdir, 'lsp-diagnostics.json')
+        with open(stale, 'w', encoding='utf-8') as fh:
+            fh.write('{"count_errors": 5, "count_warnings": 0, "diagnostics": []}')
+        with mock.patch.object(self.lp, '_detect_lsps', return_value={}):
+            self.lp.write_diagnostics_artifact(root=root, loki_dir=loki)
+        self.assertFalse(os.path.isfile(stale))
+
+    def test_deterministic_serialization(self):
+        """Same inputs -> byte-identical artifact (route + run parity)."""
+        root = self._make_repo({'src/main.py': 'x = 1\n'})
+        loki1 = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        loki2 = tempfile.mkdtemp(prefix='loki-lsp-out-')
+        fake = json.dumps({'diagnostics': [
+            {'severity': 2, 'message': 'b'},
+            {'severity': 1, 'message': 'a'},
+        ]})
+        for lk in (loki1, loki2):
+            with mock.patch.object(self.lp, '_detect_lsps',
+                                   return_value={'python': '/usr/bin/pyright'}), \
+                 mock.patch.object(self.lp, '_writer_changed_files',
+                                   return_value=['src/main.py']), \
+                 mock.patch.object(self.lp, '_lsp_get_diagnostics_blocking',
+                                   return_value=fake):
+                self.lp.write_diagnostics_artifact(root=root, loki_dir=lk)
+        with open(os.path.join(loki1, 'quality', 'lsp-diagnostics.json'), 'rb') as fh:
+            b1 = fh.read()
+        with open(os.path.join(loki2, 'quality', 'lsp-diagnostics.json'), 'rb') as fh:
+            b2 = fh.read()
+        self.assertEqual(b1, b2)
+
+
 if __name__ == '__main__':
     unittest.main()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.49.0",
+  "version": "7.51.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.49.0",
+  "version": "7.51.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/references/invariant-checks.md

@@ -0,0 +1,109 @@
+# Spec-Independent Invariant Checks (P1-4)
+
+Deterministic invariant assertions over the produced source code that hold
+regardless of what the spec says. They catch the "spec was silent and the model
+guessed wrong" failure mode: code that ships a hardcoded secret or logs PII is
+wrong no matter what the PRD asked for.
+
+Implementation: `tests/detect-invariant-violations.sh`
+Tests: `tests/test-invariant-detector.sh`
+
+## What this is (and is not)
+
+This is NOT a property-based test generator. The "Kiro Pattern" documented in
+`skills/testing.md` (fast-check / hypothesis) generates randomized property
+tests; that is a separate, larger feature and remains unimplemented. This
+detector instead makes a small set of SOLID deterministic invariant ASSERTIONS
+over the produced code. The design choice is explicit: a small set of solid
+deterministic checks beats a large set of flaky ones.
+
+## Checks
+
+### Deterministic (blocking under `--strict`)
+
+| # | Invariant | Severity | How |
+|---|-----------|----------|-----|
+| 1 | No committed secrets in source/logs | CRITICAL | Known credential prefixes: AWS access keys (`AKIA`/`ASIA`), PEM private-key blocks, GitHub tokens (`ghp_`/`gho_`/`ghs_`/`github_pat_`), Slack (`xox[baprs]-`), Google (`AIza`), Anthropic (`sk-ant-`), Stripe (`sk_live_`/`rk_live_`). Near-zero false positives. |
+| 2 | No PII (email) in logs | HIGH | An email-shaped string literal passed to a log/print call (`console.*`, `logger.*`, `print(`, `fmt.Print*`, `echo`, `System.out.print`, `log.*`). |
+
+### Advisory (never blocks)
+
+| # | Invariant | Severity | How |
+|---|-----------|----------|-----|
+| 3 | Generic secret-like assignment | MEDIUM | A variable named secret/token/password/apikey assigned a long opaque literal (and not env-var indirection). FP-prone, so advisory only. |
+| 4 | Logged email-bearing variable | LOW | A `.email` / `userEmail` style variable referenced inside a log/print call. Cannot prove PII statically. |
+
+### Deferred (honestly NOT implemented)
+
+These two requested categories are deferred because a static grep cannot do them
+deterministically without becoming flaky. They are documented here, not faked:
+
+- **No unhandled-error path on the happy route.** A grep cannot do control-flow
+  analysis; a "no try/catch near await" heuristic is noise. This belongs to a
+  real analysis pass (LSP diagnostics / typed exhaustiveness checking), tracked
+  separately as the LSP-in-verification work.
+- **Idempotency / round-trip invariants.** Not statically detectable in any
+  deterministic way worth shipping. It requires executing generated tests (the
+  larger fast-check / metamorphic-testing feature). Deferred, not faked.
+
+## False-positive avoidance
+
+Generated code legitimately contains placeholders. The detector skips them:
+
+- Placeholder allowlist on the matched line: `EXAMPLE`, `example.com`, `your-`,
+  `xxxx`, `placeholder`, `changeme`, `REPLACE`, `<...>`, `dummy`, `sample`,
+  `redact`, `sk-test-`, `fake`, `FIXME`, `TODO`, `****`. This covers AWS's own
+  documented `AKIAIOSFODNN7EXAMPLE` and `your-api-key-here`.
+- Illustration files skipped for secret checks: `*.md`, `*.example`, `*.sample`,
+  `*.template`, `*.dist` (they routinely show fake credentials on purpose).
+- Env-var indirection (`process.env`, `os.environ`, `getenv`, `ENV[`) is not a
+  hardcoded literal and is skipped for the generic check.
+
+## Scan surface
+
+Source files only. Extensions: ts, tsx, js, jsx, py, go, rb, java, rs, php, sh,
+env, yml, yaml, json, plus `*.log`. Excludes `node_modules`, `.git`, `dist`,
+`build`, `vendor`, `coverage`, and Loki's own `.loki/` telemetry.
+
+Test files are OUT OF SCOPE for all checks (consistent with the "source/logs"
+framing of this invariant). The exclusion covers every common ecosystem's test
+convention, not just the JS glob: `*.test.*` / `*.spec.*`, `test_*.py` /
+`*_test.py`, `test-*.sh`, `*_test.go`, and anything under an anchored
+`tests/` / `__tests__/` / `spec/` directory. Security/redaction test fixtures
+routinely embed realistic fake credentials on purpose, so scanning them would be
+pure noise. Comprehensive secret scanning of generated TESTS (and pre-write
+scanning) is a separate, larger feature tracked as P3-4 (#634), not this gate.
+
+## Usage
+
+```bash
+# Advisory run (prints findings, exits 0)
+tests/detect-invariant-violations.sh
+
+# CI / gate run (exits 1 iff CRITICAL or HIGH)
+tests/detect-invariant-violations.sh --strict
+
+# Scan a target project (the gate wrapper sets this)
+LOKI_SCAN_DIR=/path/to/target tests/detect-invariant-violations.sh --strict
+```
+
+Exit-code contract mirrors `tests/detect-mock-problems.sh`: `--strict` exits 1
+iff CRITICAL or HIGH findings exist; MEDIUM/LOW never block. Every HIGH (and
+CRITICAL) prints a `[HIGH]` / `[CRITICAL]` token on stdout, so a wrapper can grep
+as an alternative to relying on the exit code.
+
+## Wiring as a gate
+
+The detector is NOT wired into `autonomy/run.sh` yet. To wire it, add an
+`enforce_invariant_integrity()` wrapper next to `enforce_mock_integrity()`
+(`autonomy/run.sh:7932`) and call it where `enforce_mock_integrity` is called
+(`autonomy/run.sh:14676`). The full wrapper is documented in the header of
+`tests/detect-invariant-violations.sh`. It:
+
+- honors `LOKI_SCAN_DIR=TARGET_DIR` (the detector scans the target, not loki-mode)
+- treats detector-not-found and timeout (exit 124) as inconclusive (does not block)
+- persists findings to `${TARGET_DIR}/.loki/quality/invariant-findings.txt`
+- opts out with `LOKI_GATE_INVARIANT=false`
+
+After wiring, add a gate row to `skills/quality-gates.md` and cross-reference
+this check from the Kiro Pattern section of `skills/testing.md`.