# AgentSkeptic

## Summary

<!-- adoption-canonical-llms:start -->
## Default path: one truth check

**Start here:** **[`docs/first-truth-check.md`](docs/first-truth-check.md)** — canonical first-run steps (command, inputs, stdout/stderr, CI, Cursor, troubleshooting).

Compare recorded tool activity to downstream state (SQL and, in contract mode, HTTP witnesses, object storage, vectors, Mongo per your registry) and get **Outcome Certificate v3** on stdout (**`schemaVersion: 3`**, **`failureSpine`**, **`evidenceCompleteness`**) plus a **`truth_check_verdict`** line on stderr ([**Trust artifact naming glossary**](docs/outcome-certificate-normative.md#trust-artifact-naming-glossary) explains receipts and decision-bundle `exit.json` naming):

```bash
npx agentskeptic check --workflow-id wf_example \
  --project ./path/to/your-app \
  --db ./path/to/readable.sqlite
```

With the conventional layout, **`--registry`** and **`--events`** default to **`./path/to/your-app/agentskeptic/tools.json`** and **`events.ndjson`**. Pass them explicitly when your paths differ. Shortest path: [`docs/first-truth-check.md`](docs/first-truth-check.md). Full integrator SSOT: [`docs/integrate.md`](docs/integrate.md).

**No license required.** The default `agentskeptic check` path needs no `AGENTSKEPTIC_API_KEY` and no license server; it runs stateless contract verification locally. (Stateful **`agentskeptic enforce`** for baselines, drift, and acceptance is a later opt-in commercial path — see below.)

**Reading the result.** stdout is one **Outcome Certificate v3** line (machine JSON as above). On verdict exits, stderr begins with one of:

```text
truth_check_verdict: trusted
truth_check_verdict: not_trusted
truth_check_verdict: unknown
```

| Verdict | Meaning |
|---------|---------|
| `trusted` | Checked outcome matched expected downstream state — only this verdict means the workflow can be relied on. |
| `not_trusted` | Determinate mismatch or required state missing. Do not claim verified; fix the mismatch. |
| `unknown` | Evidence incomplete or not established. Do not claim verified; collect missing evidence or narrow checked scope. |

Full verdict and stderr contract: [`docs/first-truth-check.md`](docs/first-truth-check.md) (details in [`docs/integrate.md`](docs/integrate.md#first-truth-check)).

**Exportable activation (advanced):** `BootstrapPackInput` v1 + **`agentskeptic activate`** (writes **`proof/`** under **`--out`** on exits 0–2; **`bootstrap`** is legacy — [`docs/bootstrap-pack-normative.md`](docs/bootstrap-pack-normative.md)).

### Lifecycle

1. Keep **`agentskeptic/tools.json`** in version control; update when `toolId` → verification mapping changes.
2. Emit observations via the canonical SDK emitter, then append emitted rows to the gate buffer. Optionally mirror the same JSON lines to **`agentskeptic/events.ndjson`** for CI replay.
3. On the code path **before** irreversible work you control (ship, bill, ticket close), call **`await gate.assertSafeForIrreversibleAction()`** so **unsafe** trust (or required emissions that never reached the gate) blocks **that** branch — it is not a substitute for wiring the gate everywhere it matters, and outcomes can still be **`unknown`** when **`highStakesReliance`** is not **`permitted`** (see [`docs/outcome-certificate-normative.md`](docs/outcome-certificate-normative.md)).

### Install

```bash
npm install agentskeptic
```

### Network access (OSS CLI)

Local contract verification (for example **SQLite file** `--db`) runs **offline by default**: anonymous **product-activation telemetry** is **disabled** unless you opt in with **`AGENTSKEPTIC_TELEMETRY=1`** or persist **`{"telemetry": true}`** in **`~/.agentskeptic/config.json`**. Use **`AGENTSKEPTIC_TELEMETRY=0`** to force telemetry off. When enabled, the CLI sends best-effort anonymous usage events to AgentSkeptic’s telemetry endpoint (**`POST /api/funnel/product-activation`**); it does **not** send workflow payloads, database contents, credentials, prompts, traces, or verification artifacts. Outbound access can still occur when you explicitly configure **remote databases**, **`--share-report-origin`**, state witnesses (**HTTP / vector / S3 / Mongo**), **commercial** license or enforcement flows (**`AGENTSKEPTIC_API_KEY`**), **`funnel-anon pull`**, or when running the **`website/`** app (Stripe, email, databases, etc.).

### Code

```bash
npx agentskeptic init --framework none --database sqlite --yes
```

```ts
import { join } from "node:path";
import { AgentSkeptic } from "agentskeptic";

const skeptic = new AgentSkeptic({
  registryPath: join("agentskeptic", "tools.json"),
  databaseUrl: join(process.cwd(), "demo.db"),
});

const certificate = await skeptic.check({
  workflowId: "wf_complete",
  observations: [
    {
      toolId: "crm.upsert_contact",
      params: { recordId: "c_ok", fields: { name: "Alice", status: "active" } },
    },
  ],
});
```

### Python / LangGraph / CrewAI (same truth check)

The default verification contract is unchanged: **`agentskeptic check` semantics**, Outcome Certificate on stdout, and **`truth_check_verdict`** on stderr—whether you invoke the published **npm CLI** alongside your stack or use the **Python SDK / extras** documented in **[`docs/integrate.md`](docs/integrate.md)**. Start here: **`pip install`** and framework notes there, plus **[`examples/python-verification/README.md`](examples/python-verification/README.md)**.

See **[`docs/integrate.md`](docs/integrate.md)** (v2 integrator SSOT) and [`docs/migrate-2.md`](docs/migrate-2.md) for 1.x → 2.0 renames.

### CI (GitHub Actions)

**Default:** copy **[`examples/github-actions/agentskeptic-check.yml`](examples/github-actions/agentskeptic-check.yml)** — first-party **[composite action](https://docs.github.com/en/actions/how-tos/sharing-actions-and-workflows/recording-deployment-history-and-assignments/creating-composite-actions)** at [`.github/actions/agentskeptic-check`](.github/actions/agentskeptic-check) wrapping **`agentskeptic check`** (default **`mode`**). No `AGENTSKEPTIC_API_KEY` on the OSS path. In another repo, pin upstream with `uses: jwekavanagh/agentskeptic/.github/actions/agentskeptic-check@<ref>` (not Marketplace). Advanced CLI flags pass through **`extra-args`**. Transparent manual fallback: invoke `npx agentskeptic check …` inline (same CLI contract). Details: **[`docs/ambient-ci-distribution.md`](docs/ambient-ci-distribution.md)**.

**Opt-in commercial / stateful enforcement** (baseline, drift, acceptance): **[`examples/github-actions/agentskeptic-commercial.yml`](examples/github-actions/agentskeptic-commercial.yml)** requires an API key and license server ([`docs/commercial-enforce-gate-normative.md`](docs/commercial-enforce-gate-normative.md)).
<!-- adoption-canonical-llms:end -->
Read-only checks at verify time—not color.

## Primary links
- Canonical site: https://agentskeptic.com/
- Integrator guide (v2 SSOT): https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/docs/integrate.md
- Cursor integration (consumer rule): https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/docs/cursor-integration.md
- First-run integration: https://agentskeptic.com/integrate
- Runtime truth-check (agentskeptic check / AgentSkeptic.check): https://github.com/jwekavanagh/agentskeptic/blob/main/docs/first-truth-check.md
- Learn: https://agentskeptic.com/guides
- OpenAPI (hosted commercial / reporting / enforcement): https://agentskeptic.com/openapi-commercial-v1.yaml
- OpenAPI (repo raw): https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/schemas/openapi-commercial-v1.yaml
- Source repository: https://github.com/jwekavanagh/agentskeptic
- npm package: https://www.npmjs.com/package/agentskeptic
- llms.txt (repo raw): https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/llms.txt
- Verification Contract Manifest (canonical): https://agentskeptic.com/contract/v1.json
- Verification Contract Manifest (repo raw): https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/schemas/contract/v1.json

## Evidence retention (progressive)

- Default truth check: `agentskeptic check` — Outcome Certificate on stdout; no bundle files written unless you opt in.
- Decision evidence on disk: add `--proof <dir>` or `--write-decision-bundle <dir>`.
- Full local proof (technical + decision bundles): add `--write-run-bundle <dir>` alongside `--write-decision-bundle` (two output directories).
- Hosted commercial `GET /api/v1/governance/export` returns `GovernanceAuditBundleV3` (`schemaVersion: 3`) with slice-keyed `evidenceSlices` — not a CLI `decision bundle` / `write-run-bundle` directory.

- Operational SSOT (artifact names, completeness, handoff zip recipe): https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/docs/decision-evidence-bundle.md

## Indexable guides
- https://agentskeptic.com/guides/ai-agent-wrong-crm-data
- https://agentskeptic.com/guides/automation-success-database-mismatch
- https://agentskeptic.com/guides/buyer-ci-enforcement-metering
- https://agentskeptic.com/guides/buyer-commercial-boundary
- https://agentskeptic.com/guides/buyer-trust-production-implications
- https://agentskeptic.com/guides/ci-green-logs-row-absent
- https://agentskeptic.com/guides/ci-green-missing-database-side-effect
- https://agentskeptic.com/guides/debug-postgres-after-langgraph
- https://agentskeptic.com/guides/first-run-verification
- https://agentskeptic.com/guides/pre-production-read-only-sql-gate
- https://agentskeptic.com/guides/scenario-agent-crm-silent-drift
- https://agentskeptic.com/guides/scenario-ci-green-side-effect-missing
- https://agentskeptic.com/guides/scenario-green-trace-row-missing
- https://agentskeptic.com/guides/scenario-preprod-gate-before-ship
- https://agentskeptic.com/guides/scenario-stripe-webhook-ledger-mismatch
- https://agentskeptic.com/guides/stripe-webhook-database-alignment
- https://agentskeptic.com/guides/tool-loop-success-crm-state-wrong
- https://agentskeptic.com/guides/trace-green-postgres-row-missing
- https://agentskeptic.com/guides/verify-langgraph-workflows

## Indexable examples
- https://agentskeptic.com/examples/langgraph-checkpoint-trust
- https://agentskeptic.com/examples/wf-complete
- https://agentskeptic.com/examples/wf-missing

## Indexable comparisons
- https://agentskeptic.com/compare/evals-vs-row-gates
- https://agentskeptic.com/compare/observability-vs-preaction-gate
- https://agentskeptic.com/compare/traces-vs-read-only-sql-verification

## Bundled terminal proof

```text
### Success (`wf_complete`) — canonical `agentskeptic check`

stderr (first line): truth_check_verdict: trusted
stdout (Outcome Certificate excerpt): {"schemaVersion":3,"workflowId":"wf_complete","runKind":"contract_sql","stateRelation":"matches_expectations"}

### Failure (`wf_missing`)

stderr (first line): truth_check_verdict: not_trusted
Human report then explains ROW_ABSENT (missing downstream row vs registry expectation).
stdout (Outcome Certificate excerpt): {"schemaVersion":3,"workflowId":"wf_missing","runKind":"contract_sql","stateRelation":"does_not_match"}
```

## Intent phrases
- trace v data
- read-only verify
- ROW_ABSENT

## Not for
- logs
- HTTP proof
- no store

## Related queries
- langgraph
- agent verify
- trace data

## When this hurts (search-shaped)
- Green trace, bad data — https://agentskeptic.com/guides/trace-green-postgres-row-missing
- Tool OK, CRM wrong — https://agentskeptic.com/guides/tool-loop-success-crm-state-wrong
- CI green, no write — https://agentskeptic.com/guides/ci-green-logs-row-absent
- Pre-production read-only gate — https://agentskeptic.com/guides/pre-production-read-only-sql-gate
- LangGraph data check — https://agentskeptic.com/guides/debug-postgres-after-langgraph
- Webhook vs ledger — https://agentskeptic.com/guides/stripe-webhook-database-alignment

## Problem framing (shareable)
- Full page: https://agentskeptic.com/database-truth-vs-traces

## Visitor problem (canonical answer)

Traces can show success while stored data disagrees.

AgentSkeptic re-checks the stores your agent claims to change, then returns a deterministic Outcome Certificate before you ship.