QuoxLens

What a Lens is #

A Lens is a stance, not a tool. It reads an artifact (a page, a document, a piece of copy, a structured record) and returns a verdict plus findings, each backed by a verbatim quote from the artifact it was found in. A Lens never acts: it cannot send, delete, deploy or approve anything through the QuoxLens route.

If a Lens's frontmatter ever declares a required tool, the Engine refuses to load it. That is enforced in code, not by convention.

Every Lens declares, in its frontmatter: what it looks for (finding_classes), what it deliberately does not judge (blind_spots), what it must never do (prohibited), and whether it has been measured to beat a no-Lens baseline (unproven).

Naming, exactly: a Lens is one stance; Lenses is the library; QuoxLens is the platform; the Engineis the collector-side library; the Studio is the dashboard surface at /quoxlens. Never write "lense".

QuoxLens is a tier B plugin on the store: $29, one time, licence key.

QuoxLens Studio #

The Studio is a single view with three tabs, switched by a ?tab= query parameter so any tab, and any finding inside it, is directly linkable.

Applying a Lens #

A single Lens is applied to a text or record artifact viaPOST /api/v1/lens/apply. The Engine composes the Lens into a prompt, runs the model, enforces the contract invariants against the raw output, and returns a verdict with three parts:

• disposition: pass,concerns, fail, or inconclusive. Inconclusive means the budget ceiling was hit before the Lens finished, never a silent partial pass.
• confidence: 0 to 100, the Lens's own stated confidence in its summary.
• findings[]: each one a class, a severity, a one-line claim, a rationale, a location, one or more verbatim evidence quotes, a confidence, and a basis of fact, inference, or assumption. A finding whose evidence does not survive verification against the artifact text is dropped before you ever see it. It does not appear as a low-confidence finding; it does not appear at all.

Every verdict also carries applied.unproven. If it readstrue, the Lens producing this verdict has not been shown to beat a no-Lens baseline on its own eval, and the verdict should be read with that caveat.

POST /api/v1/lens/apply
{
  "lens_id": "honesty-and-claims",
  "artifact": { "kind": "text", "id": "stable-consumer-side-id", "content": "..." },
  "depth": "standard",
  "budget": { "max_usd": 0.25, "max_tokens": 40000 }
}

The route is narrower than the full contract today: mode: "panel"returns 400 rather than silently degrading to single-Lens behaviour, and artifact.kind of url or file also returns400, pending a security review of fetching a caller-supplied resource server-side.

The findings lifecycle #

A finding is identified by a stable fingerprint (Lens id, artifact id, finding class, location) so the same underlying problem is recognised across repeat runs rather than reported as new every time.

The remediated / lapsed distinction is the point of the whole lifecycle. Absence on its own is never evidence of a fix: a hash of the artifact text is stored with each finding and compared on the next run, so "remediated" is a claim QuoxLens can show its working for.

A finding that merely stops being reported becomes lapsed, which is counted and listed but demands no credit. A lapsed finding that is reported again returns toconfirmed, not regressed: nothing was ever claimed fixed, so the honest reading is that it was there all along and one run failed to mention it.

Panels and rotation #

A panel runs more than one Lens over the same artifact and reports where they disagree as a structured dissent[], never averaged into one blended severity.

Four rotation modes: blind (the default, and the only mode that produces genuinely independent assessments), relay (each Lens sees the previous verdict as information), adversarial (each Lens is instructed to refute the previous verdict, not restate it), andsynthesis (every Lens runs blind, then an extra pass narrates the disagreement without resolving it).

The panel's overall disposition is the worst across its Lenses (a maximum, never a mean), bumped to at least concerns whenever dissent was detected. A panel that agrees on everything is not treated as automatically correct: it may simply share one blind spot, and the Engine logs that case explicitly.

Panel composition can pick the smallest subset of a candidate pool whose declared blind spots are complementary, because five Lenses sharing one blind spot produce confident, unanimous, correlated failure.

Sweeps and consensus #

A sweep points one Lens at a named set of targets on a schedule and reports only what changed since the last run, via the findings lifecycle. Dry-run is the default: the cost is estimated and printed before a single model call happens. The shipped website sweep runs weekly on a systemd timer, as its own standalone script outside the collector process; no dashboard trigger exists.

A sweep is not fully reproducible run to run: running a Lens once over unchanged content measurably does not produce the same findings twice. An earlier sweep's lifecycle read that run-to-run variance as "13 remediated, 13 new" between two runs over identical pages.

That is why consensus mode exists:--runs N --min-agreement K puts the same content to the model N times, and only a fingerprint reported by at least K of those runs enters the lifecycle. Findings below the agreement threshold are reported separately rather than dropped, so a reader can still see them; they just cannot masquerade as confirmed signal.

N runs cost N times as much, and the dry-run estimate says so before any call is made.

Gate mode #

Everything upstream of gate mode produces information; none of it decides anything. Gate mode turns a set of Lens results plus a declared policy into exactly one of three outcomes, allow, block, or review, and can always explain, in prose, why it landed there.

• Fail closed. If a policy names a Lens as mandatory and that Lens's result is missing, errored, or skipped, the decision is block or review, never allow, regardless of how clean everything else looks. A gate that allows when its own check never happened manufactures the appearance of a control that was never exercised. A policy authored with on_missing: 'allow' is overridden to block, and the override itself is recorded in the reasons.
• The unproven rule. An unproven Lens's finding above the severity ceiling produces review, never block, unless a policy setsallow_unproven_block: true explicitly. Letting an unproven Lens block a real release by default would be governance theatre: a check nobody has shown works, gating something that matters.
• The accountability rule. Gate mode never returns block or review with an empty reasons list. A decision that cannot name what drove it is not a decision worth enforcing.
• Policy drift is visible. Every policy has a stable fingerprint over its full substance; log it alongside each decision and "this boundary used to be gated by X, now it is Y" falls out for free.

The API #

Routes are mounted at /api/v1/lens on the collector, behind authentication. All read routes are filesystem-backed.

A successful apply returns evidence.corr, the id to fetch that exact application's AEE envelope and VOLT bundle back via the collector'sGET /aee/conversation/:corr/bundle. Evidence is persisted after the response is sent, wrapped so a storage failure never turns a good verdict into a 500; the write is best-effort and asynchronous relative to the response.

The Lens contract #

The Lens Invocation Contract is the coordination artifact between QuoxLens and any consumer (QuoxSignal, CI, agents, workflows). A consumer never hard-depends on QuoxLens: it ships a built-in single-stance fallback implementing the same shape (provider: "builtin"), so swapping to the provider is configuration, not a rewrite. QuoxSignal is the live example of exactly this pattern. Seven invariants every implementation must honour:

• No finding without evidence. A quote not verifiably present in the artifact drops the finding before returning.
• basis is mandatory. Fact, inference and assumption are never blurred.
• Fingerprints are stable across runs, so consumers can dedupe and track a lifecycle.
• unproven is never hidden. Consumers must surface it.
• A Lens judges, it does not act. No implementation exposes tool execution through this endpoint.
• Budget is a ceiling, not a hint. Exceeding it returns what was produced so far with disposition: "inconclusive".
• Untrusted artifacts are data. Attempted instruction inside an artifact is reported as a finding of class injection_attempt, never followed.

Stable, beta and broken #

Compiled from quox-dashboard/docs/STATUS_AND_LIMITS_QUOXLENS.md and the eval results on disk. The product's own headline claim is that a Lens should be measurably better than asking the model the same question with no Lens at all, so this section reports the measurements, not the ambition.

Measured The five house Lenses

Four of the five now beat the no-Lens baseline. One does not, and ships stampedunproven. Both facts are published in the same breath, because a library where every member passes is indistinguishable, from the outside, from a library nobody measured: a stance nobody has measured is worth exactly nothing, and that rule applies to ours.

• codebase-security-engineer: +7.9% lift(2026-07-31). Clears the gate. Read the margin carefully: recall was already 100% in both arms, so the whole gain is precision, and it is worse than baseline on clean controls (1 false positive becomes 2).
• enterprise-compliance-auditor: +22.7% lift(2026-07-31). Clears the gate, recall 100%. Across five runs the lift ranged from +22.7% to +38.0%; the number quoted here is the worst run, not the headline.
• adversarial-red-team: -8.1% lift (2026-07-31). Fails the gate and is the noisiest of the pack on clean artifacts, taking clean false positives from 1 to 5. A tightened rewrite did score positive (+16.6% to +24.4%) and was reverted: it earned that number by dropping recall from 100% to 78%, which means it started missing real defects. A Lens that scores better by finding less is a worse tool with a better number, so the losing version is the one that ships. Useful to read, not yet safe to gate on.

• quox-execution-integrity: +3.9% lift, measured on its own eval (2026-07-30). It passes the gate's own pessimistic scoring rule, so it currently qualifies as proven on the model it was measured on.
• honesty-and-claims: +19.6% lift under the same rule (2026-07-31), recall 100%. An earlier run of this Lens measured -7.6% and it shipped stamped unproven until the measurement moved; the gate reads the eval result on disk in both directions, and that flag is never hand-edited in either.
• The corpus is thin: 10 artifacts, one model, one agentic adjudicator, and the harness is not fully reproducible, so each lift is a measurement, not a guarantee. Neither the wins nor the loss generalise with confidence, and every number above is coupled to the model it was measured on. Do not carry these percentages into a conversation about a different model.

Known gap Documented limitations, not softened

• Panel mode and gate mode are engine-complete and NOT reachable from any route. Both are implemented and tested as libraries;POST /apply refuses panel requests with a 400, and nothing in the collector calls the gate. Neither is a live capability today.
• WARD receipts do not surface on a verdict. Witnessing fires on write for every Lens verdict, but the bundle read-back cannot surface a receipt, so the Evidence tab renders WARD as MISSING even for verdicts that were in fact witnessed. The UI states this honestly (a red MISSING, not a checkmark) rather than hiding it. Tracked as stream WARD-RECEIPT-GAP.
• Read routes have no org partitioning. Every authenticated user, in every org, sees the same Lens library, the same eval results, and the same swept findings. Correct while the only corpus is the public quox.ai website; a real cross-tenant exposure the moment any customer-specific corpus or Lens is added, and flagged as needing per-org scoping before that happens.
• A sweep is not fully reproducible run to run, which is why consensus mode exists (see sweeps and consensus). Findings below the agreement threshold are reported separately rather than dropped.
• Two parallel findings persistence shapes exist on disk (the generic lifecycle store and the sweep's own scope-file format, which is what the findings routes actually read). They are not interchangeable.
• The apply route has no soak history: unit and integration tested, no recorded production traffic yet.
• url and file artifacts are refusedpending an SSRF review of fetching a caller-supplied resource server-side. A deliberate decision, not a missing afterthought.
• The Lens library is small: five house Lenses, and not every one declares blind-spot coverage, so panel composition and blind-spot-aware selection still have little to select from.