agentskeptic 7.1.4 → 7.2.0

package/README.md

@@ -58,6 +58,8 @@ steps:
 <!-- adoption-canonical: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 an **Outcome Certificate** (stdout) plus a **`truth_check_verdict`** line on stderr:
 
 ```bash
@@ -66,7 +68,25 @@ npx agentskeptic check --workflow-id wf_example \
   --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. Full reference: [`docs/integrate.md`](integrate.md).
+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 the **Outcome Certificate** (machine JSON). 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)).
 
@@ -143,7 +163,8 @@ Read-only checks at verify time—not color.
 - **npm package:** https://www.npmjs.com/package/agentskeptic
 - **Canonical site:** https://agentskeptic.com
 - **Integrate:** https://agentskeptic.com/integrate
-- **OpenAPI (canonical):** https://agentskeptic.com/openapi-commercial-v1.yaml
+- **Runtime truth-check (CLI / SDK):** https://github.com/jwekavanagh/agentskeptic/blob/main/docs/first-truth-check.md
+- **OpenAPI (hosted commercial API):** https://agentskeptic.com/openapi-commercial-v1.yaml
 - **Verification Contract Manifest:** https://agentskeptic.com/contract/v1.json
 - **llms.txt (agents, site):** https://agentskeptic.com/llms.txt
 - **llms.txt (repo, raw):** https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/llms.txt
@@ -161,15 +182,17 @@ This is the fastest way to see **`ROW_ABSENT`** versus **verified** on the same
 
 **Prerequisite:** **Node.js ≥ 22.13** (built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html)), or use [Docker](#docker-quickstart-optional) below.
 
-**Fast first run on your own DB (canonical local truth loop):** after `npm install` and `npm run build`, run:
+**Fast first run on your own DB:** run the same `agentskeptic check` from the [Default path](#default-path-one-truth-check) above against your inputs — after `npm install` and `npm run build`:
 
 ```bash
-agentskeptic loop --workflow-id <id> --events <path> --registry <path> --db <sqlitePath>
+agentskeptic check --workflow-id <id> --events <path> --registry <path> --db <sqlitePath>
 ```
 
-This single command verifies state, emits **TRUSTED / NOT TRUSTED / UNKNOWN**, shows a next action when non-trusted, persists local run history, and auto-compares against your latest compatible prior run. Normative operator contract: **[`docs/local-feedback-loop.md`](docs/local-feedback-loop.md)**.
+stdout is the Outcome Certificate; stderr begins with `truth_check_verdict: trusted|not_trusted|unknown` plus the human report.
+
+**Local feedback loop with run history (advanced):** `agentskeptic loop` wraps the same `check` contract and adds local run history, prior-run comparison, and a single TRUSTED / NOT TRUSTED / UNKNOWN line for tight inner-loop iteration — normative contract: [`docs/local-feedback-loop.md`](docs/local-feedback-loop.md).
 
-**Advanced compatibility paths:** `agentskeptic quick`, `agentskeptic crossing`, and `agentskeptic verify-integrator-owned` remain supported for specialized workflows and CI parity; they are no longer the default local operator path.
+**Advanced compatibility paths:** `agentskeptic quick`, `agentskeptic crossing`, and `agentskeptic verify-integrator-owned` remain supported for specialized workflows and CI parity; they are not the first-run path.
 
 ```bash
 npm install
@@ -254,17 +277,17 @@ Retries, partial failures, and race conditions mean a success flag in a trace is
 
 ## Contract path (registry + events)
 
-**CLI:** after **`npm install`** and **`npm run build`**, use **`agentskeptic loop`** as the default local command (or `node dist/cli.js loop`). Postgres: **`--postgres-url`** instead of **`--db`** (exactly one).
+**CLI:** the canonical local replay command is **`agentskeptic check`** (see [Default path](#default-path-one-truth-check) above) — the same command CI and the Cursor rule wrap. After **`npm install`** and **`npm run build`**, run it via `agentskeptic check` (or `node dist/cli.js check`). Postgres: **`--postgres-url`** instead of **`--db`** (exactly one).
 
 Typical integration:
 
 1. Emit **one NDJSON line per tool observation** (see [Event line schema](docs/agentskeptic.md#event-line-schema)).
 2. Add a **registry** entry per `toolId` (start from **`examples/templates/`**).
-3. Run the local truth loop:
+3. Run the truth check:
 
 ```bash
 npm run build
-agentskeptic loop --workflow-id <id> --events <path> --registry <path> --db <sqlitePath>
+agentskeptic check --workflow-id <id> --events <path> --registry <path> --db <sqlitePath>
 ```
 
 Replay the bundled files: **`wf_complete`** / **`examples/events.ndjson`** / **`examples/tools.json`** / **`examples/demo.db`** (same flags as above).

package/config/marketing.json

@@ -86,7 +86,7 @@
     "quickVerifyCommand": "npx agentskeptic quick \\\n  --input path/to/quick-input.ndjson \\\n  --export-registry path/to/tools.json \\\n  --db path/to/readable.sqlite \\\n  --no-human-report",
     "packLedCommand": "npx agentskeptic activate --input ./path/to/workflow-bootstrap-input.json \\\n  --db ./path/to/readable.sqlite \\\n  --out ./path/to/agent-pack\n\nnpx agentskeptic crossing \\\n  --workflow-id YOUR_WORKFLOW_ID \\\n  --events ./path/to/events.ndjson \\\n  --registry ./path/to/tools.json \\\n  --db ./path/to/readable.sqlite",
     "githubDeepLink": "https://github.com/jwekavanagh/agentskeptic/blob/main/docs/integrate.md",
-    "githubFirstRunLink": "https://github.com/jwekavanagh/agentskeptic/blob/main/docs/integrate.md"
+    "githubFirstRunLink": "https://github.com/jwekavanagh/agentskeptic/blob/main/docs/first-truth-check.md"
   },
   "briefProblem": "Claims vs read-only; ROW_ABSENT.",
   "briefSections": [],

package/dist/discovery-payload-v1.json

@@ -5,6 +5,7 @@
   "links": {
     "site": "https://agentskeptic.com/",
     "integrate": "https://agentskeptic.com/integrate",
+    "runtimeTruthCheckGuide": "https://github.com/jwekavanagh/agentskeptic/blob/main/docs/first-truth-check.md",
     "learnHub": "https://agentskeptic.com/guides",
     "openapiCanonical": "https://agentskeptic.com/openapi-commercial-v1.yaml",
     "openapiRaw": "https://raw.githubusercontent.com/jwekavanagh/agentskeptic/refs/heads/main/schemas/openapi-commercial-v1.yaml",

package/dist/execution-identity.v1.json

@@ -4,7 +4,7 @@
   "identityVersion": "1.0.0",
   "mergeGateFingerprintSha256": "64b5ae2ed5025c08c7c9d7b601958cc90edc32c0d80ea207fdaa373de5b9c2fc",
   "nodeEnginesDeclared": "22.x || 24.x",
-  "npmPackageVersion": "7.1.4",
+  "npmPackageVersion": "7.2.0",
   "pythonPipExtrasFragment": "dev,postgres",
   "verificationContractManifest": {
     "manifestSha256": "c5f23ec43576716c4b9a13e752cd2962a78bb4b4da1f9e521f911e15dfd80268",

package/dist/publicDistribution.generated.d.ts

@@ -1,5 +1,5 @@
 export declare const PUBLIC_DISTRIBUTION_SSOT_BLOB_URL = "https://github.com/jwekavanagh/agentskeptic/blob/main/docs/public-distribution.md";
 export declare const PUBLIC_CANONICAL_SITE_ORIGIN = "https://agentskeptic.com";
-export declare const AGENTSKEPTIC_CLI_SEMVER = "7.1.4";
+export declare const AGENTSKEPTIC_CLI_SEMVER = "7.2.0";
 export declare function formatDistributionFooter(): string;
 //# sourceMappingURL=publicDistribution.generated.d.ts.map

package/dist/publicDistribution.generated.js

@@ -1,7 +1,7 @@
 // Generated by npm run emit-primary-marketing — do not hand edit.
 export const PUBLIC_DISTRIBUTION_SSOT_BLOB_URL = "https://github.com/jwekavanagh/agentskeptic/blob/main/docs/public-distribution.md";
 export const PUBLIC_CANONICAL_SITE_ORIGIN = "https://agentskeptic.com";
-export const AGENTSKEPTIC_CLI_SEMVER = "7.1.4";
+export const AGENTSKEPTIC_CLI_SEMVER = "7.2.0";
 export function formatDistributionFooter() {
     return "Context: https://agentskeptic.com/database-truth-vs-traces\n"
         + "https://agentskeptic.com/integrate\n"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentskeptic",
-  "version": "7.1.4",
+  "version": "7.2.0",
   "description": "Tool activity vs downstream state at verify: SQL, HTTP, vectors, documents, S3 objects—deterministic verdict artifacts (verification-state-stores.md).",
   "license": "MIT",
   "type": "module",

package/schemas/openapi-commercial-v1.in.yaml

@@ -14,8 +14,16 @@ info:
     manifestSha256: __CONTRACT_SHA__
   description: "__IDENTITY_ONE_LINER__\n\nMachine-readable contract for license preflight used by the published npm CLI.\nBase URL is your deployed app origin (same as NEXT_PUBLIC_APP_URL).\n\nEvery path in this document returns an `x-request-id` response header on all status codes (echo a valid client `x-request-id` when supplied; otherwise server-generated). Non-2xx JSON bodies follow RFC 7807-style Problem Details (`type`, `title`, `status`, `detail`, optional `code`, `instance`) unless noted; `POST /api/v1/usage/reserve` denials additionally include legacy `allowed`, `code`, `message`, and optional `upgrade_url` for backward compatibility.\n\n**Breaking (agentskeptic 5.x):** Hosted enforcement ingestion uses `schema_version` 3 with `outcome_certificate` (Outcome Certificate v3 inner JSON, including `failureSpine`). Legacy `schema_version` 2 payloads with `outcome_certificate_v1` are rejected. `POST /api/v1/funnel/verify-outcome` requires `schema_version` 3 and `evidence_gap_primary`. `POST /api/public/verification-reports` accepts envelope `schemaVersion` 3 only. **HTTP 4xx/5xx** responses are **not** `failure-spine-v1` and are **not** Outcome Certificate-shaped; operational CLI errors use `cli-error-envelope` on stderr only.\n"
 externalDocs:
-  description: "First-run integration guide"
+  description: Runtime truth-check integration guide for agentskeptic check and AgentSkeptic.check
   url: __DISTRIBUTION_INTEGRATE_URL__
+x-agentskeptic-runtime-truth-check:
+  status: documented-outside-commercial-api
+  cli: agentskeptic check
+  sdk: AgentSkeptic.check
+  note: >
+    This OpenAPI file describes hosted commercial, reporting, and enforcement APIs. Runtime
+    truth checks are integrated through the CLI or SDK. Demo /api/verify routes are examples,
+    not the production hosted truth-check API.
 servers:
   - url: __SERVERS_ORIGIN__
     description: Replace with your deployment origin

package/schemas/openapi-commercial-v1.yaml

@@ -1,7 +1,7 @@
 openapi: "3.0.3"
 info:
   title: AgentSkeptic commercial license API
-  version: "7.1.4"
+  version: "7.2.0"
   contact:
     url: https://agentskeptic.com
   x-agentskeptic-distribution:
@@ -14,8 +14,16 @@ info:
     manifestSha256: "c5f23ec43576716c4b9a13e752cd2962a78bb4b4da1f9e521f911e15dfd80268"
   description: "Read-only checks at verify time—not color.\n\nMachine-readable contract for license preflight used by the published npm CLI.\nBase URL is your deployed app origin (same as NEXT_PUBLIC_APP_URL).\n\nEvery path in this document returns an `x-request-id` response header on all status codes (echo a valid client `x-request-id` when supplied; otherwise server-generated). Non-2xx JSON bodies follow RFC 7807-style Problem Details (`type`, `title`, `status`, `detail`, optional `code`, `instance`) unless noted; `POST /api/v1/usage/reserve` denials additionally include legacy `allowed`, `code`, `message`, and optional `upgrade_url` for backward compatibility.\n\n**Breaking (agentskeptic 5.x):** Hosted enforcement ingestion uses `schema_version` 3 with `outcome_certificate` (Outcome Certificate v3 inner JSON, including `failureSpine`). Legacy `schema_version` 2 payloads with `outcome_certificate_v1` are rejected. `POST /api/v1/funnel/verify-outcome` requires `schema_version` 3 and `evidence_gap_primary`. `POST /api/public/verification-reports` accepts envelope `schemaVersion` 3 only. **HTTP 4xx/5xx** responses are **not** `failure-spine-v1` and are **not** Outcome Certificate-shaped; operational CLI errors use `cli-error-envelope` on stderr only.\n"
 externalDocs:
-  description: "First-run integration guide"
-  url: https://agentskeptic.com/integrate
+  description: Runtime truth-check integration guide for agentskeptic check and AgentSkeptic.check
+  url: https://github.com/jwekavanagh/agentskeptic/blob/main/docs/first-truth-check.md
+x-agentskeptic-runtime-truth-check:
+  status: documented-outside-commercial-api
+  cli: agentskeptic check
+  sdk: AgentSkeptic.check
+  note: >
+    This OpenAPI file describes hosted commercial, reporting, and enforcement APIs. Runtime
+    truth checks are integrated through the CLI or SDK. Demo /api/verify routes are examples,
+    not the production hosted truth-check API.
 servers:
   - url: https://agentskeptic.com
     description: Replace with your deployment origin

package/scripts/discovery-payload.lib.cjs

@@ -30,6 +30,8 @@ const STDERR_TAIL_LINES = 20;
 /** Max UTF-8 bytes of stdout parsed for Outcome Certificate JSON (`failureSpine` extraction). */
 const MAX_STDOUT_PARSE_BYTES = 262144;
 
+const { runtimeTruthCheckGuideBlobUrl } = require("./origin.cjs");
+
 const REPO_ROOT = join(__dirname, "..");
 const README_ADOPTION_START = "<!-- adoption-canonical:start -->";
 const README_ADOPTION_END = "<!-- adoption-canonical:end -->";
@@ -141,6 +143,7 @@ function buildDiscoveryPayload(root) {
   const anchors = pm;
   const canonicalOrigin = normalizeOrigin(anchors.productionCanonicalOrigin);
   const integrateUrl = `${canonicalOrigin}/integrate`;
+  const runtimeTruthCheckGuideUrl = runtimeTruthCheckGuideBlobUrl(String(anchors.gitRepositoryUrl));
   const learnHubUrl = `${canonicalOrigin}/guides`;
   const openapiSelfCanonical = `${canonicalOrigin}/openapi-commercial-v1.yaml`;
   const { owner, repo } = parseGithubRepoFromUrl(anchors.gitRepositoryUrl);
@@ -162,6 +165,7 @@ function buildDiscoveryPayload(root) {
     links: {
       site: `${canonicalOrigin}/`,
       integrate: integrateUrl,
+      runtimeTruthCheckGuide: runtimeTruthCheckGuideUrl,
       learnHub: learnHubUrl,
       openapiCanonical: openapiSelfCanonical,
       openapiRaw,
@@ -259,8 +263,9 @@ function renderLlmsTextFromPayload(payload) {
     `- Integrator guide (v2 SSOT): ${links.integratorGuideSsotRaw}`,
     `- Cursor integration (consumer rule): ${links.cursorIntegrationDocRaw}`,
     `- First-run integration: ${integrateUrl}`,
+    `- Runtime truth-check (agentskeptic check / AgentSkeptic.check): ${links.runtimeTruthCheckGuide}`,
     `- Learn: ${learnHubUrl}`,
-    `- OpenAPI (canonical): ${openapiSelfCanonical}`,
+    `- OpenAPI (hosted commercial / reporting / enforcement): ${openapiSelfCanonical}`,
     `- OpenAPI (repo raw): ${links.openapiRaw}`,
     `- Source repository: ${links.repo}`,
     `- npm package: ${links.npm}`,
@@ -289,8 +294,9 @@ function renderCiSummaryMarkdownFromPayload(payload) {
     "",
     "- Canonical site: " + L.site,
     "- Integrate: " + L.integrate,
+    "- Runtime truth-check (CLI/SDK): " + L.runtimeTruthCheckGuide,
     "- Learn: " + L.learnHub,
-    "- OpenAPI: " + L.openapiCanonical,
+    "- OpenAPI (hosted commercial): " + L.openapiCanonical,
     "- OpenAPI (repo raw): " + L.openapiRaw,
     "- Cursor integration (consumer rule): " + L.cursorIntegrationDocRaw,
     "- Repository: " + L.repo,

package/scripts/emit-primary-marketing.cjs

@@ -2,7 +2,7 @@
 
 const { readFileSync, writeFileSync, mkdirSync } = require("node:fs");
 const { join, dirname } = require("node:path");
-const { normalize, assertNextPublicOriginParity, MARKETING_PATH } = require("./origin.cjs");
+const { normalize, runtimeTruthCheckGuideBlobUrl, assertNextPublicOriginParity, MARKETING_PATH } = require("./origin.cjs");
 
 const ROOT = join(__dirname, "..");
 
@@ -238,7 +238,8 @@ function syncPrimaryMarketing() {
   const publicOriginNormalized = normalize(effectivePublicOrigin);
   const openapiSelfEffective = `${publicOriginNormalized}/openapi-commercial-v1.yaml`;
 
-  const integrateUrl = `${canonicalOrigin}/integrate`;
+  const integrateLandingUrl = `${canonicalOrigin}/integrate`;
+  const integrateRuntimeTruthGuideUrl = runtimeTruthCheckGuideBlobUrl(anchors.gitRepositoryUrl);
 
   const template = readFileSync(OPENAPI_IN, "utf8");
   const pkgForVersion = JSON.parse(readFileSync(PKG_PATH, "utf8"));
@@ -252,7 +253,7 @@ function syncPrimaryMarketing() {
   mid = mid.replace(PRODUCT_VERSION_TOKEN, JSON.stringify(productSemver));
   mid = mid.replace("__IDENTITY_ONE_LINER__", escaped);
   mid = mid.replace("__DISTRIBUTION_CONTACT_URL__", canonicalOrigin);
-  mid = mid.replace("__DISTRIBUTION_INTEGRATE_URL__", integrateUrl);
+  mid = mid.replace("__DISTRIBUTION_INTEGRATE_URL__", integrateRuntimeTruthGuideUrl);
   mid = mid.replace("__DISTRIBUTION_REPO_URL__", anchors.gitRepositoryUrl);
   mid = mid.replace("__DISTRIBUTION_NPM_URL__", anchors.npmPackageUrl);
   mid = mid.replace("__CONTRACT_URL__", contractPin.url);
@@ -324,8 +325,9 @@ function syncPrimaryMarketing() {
     `- **Repository:** ${anchors.gitRepositoryUrl}`,
     `- **npm package:** ${anchors.npmPackageUrl}`,
     `- **Canonical site:** ${canonicalOrigin}`,
-    `- **Integrate:** ${integrateUrl}`,
-    `- **OpenAPI (canonical):** ${openapiSelfCanonical}`,
+    `- **Integrate:** ${integrateLandingUrl}`,
+    `- **Runtime truth-check (CLI / SDK):** ${integrateRuntimeTruthGuideUrl}`,
+    `- **OpenAPI (hosted commercial API):** ${openapiSelfCanonical}`,
     `- **Verification Contract Manifest:** ${contractPin.url}`,
     `- **llms.txt (agents, site):** ${canonicalOrigin}/llms.txt`,
     `- **llms.txt (repo, raw):** ${pl.llmsRaw}`,

package/scripts/origin.cjs

@@ -31,6 +31,17 @@ function readProductionCanonicalOrigin() {
   return String(pm.productionCanonicalOrigin);
 }
 
+/**
+ * Canonical browser URL for the repo markdown SSOT `docs/first-truth-check.md` (OpenAPI externalDocs + discovery).
+ * @param {string} gitRepositoryUrl e.g. https://github.com/org/repo or …/repo.git
+ */
+function runtimeTruthCheckGuideBlobUrl(gitRepositoryUrl) {
+  const base = String(gitRepositoryUrl)
+    .replace(/\.git$/i, "")
+    .replace(/\/$/, "");
+  return `${base}/blob/main/docs/first-truth-check.md`;
+}
+
 function assertNextPublicOriginParity() {
   const canonicalFromJson = readProductionCanonicalOrigin();
   const skip = process.env.NODE_ENV !== "production" || process.env.VERCEL_ENV === "preview";
@@ -45,6 +56,7 @@ function assertNextPublicOriginParity() {
 
 module.exports = {
   normalize,
+  runtimeTruthCheckGuideBlobUrl,
   assertNextPublicOriginParity,
   MARKETING_PATH,
   /** @deprecated use MARKETING_PATH */