agentskeptic 7.1.4 → 7.3.0

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.3.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
@@ -228,7 +236,14 @@ paths:
   /api/v1/governance/export:
     get:
       operationId: exportGovernanceAuditBundle
-      summary: Export governance audit bundle for one workflow (session auth)
+      summary: Export governance timeline JSON for one workflow (session auth)
+      description: >
+        **Breaking:** Returns GovernanceAuditBundleV3 only (schemaVersion 3). Includes governance window, lifecycle,
+        baselines, timeline rows, and slice-keyed evidenceSlices (per governance_evidence row: Outcome Certificate v3,
+        fingerprints, hostedExit, decisionCompleteness, truthCheckVerdict). Not equivalent to CLI --write-run-bundle
+        (NDJSON technical bundle) or full on-disk decision directories; see docs/decision-evidence-bundle.md.
+        If any referenced evidence row fails v3 validation or stored fingerprints disagree with recomputed hashes,
+        responds 500 CORRUPTED_EVIDENCE_ROW with a fixed JSON body (no degraded export).
       parameters:
         - name: workflow_id
           in: query
@@ -249,11 +264,11 @@ paths:
             format: date-time
       responses:
         "200":
-          description: Governance audit bundle
+          description: GovernanceAuditBundleV3 governance timeline + slice-keyed evidence
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/GovernanceAuditBundleV2"
+                $ref: "#/components/schemas/GovernanceAuditBundleV3"
         "400":
           description: Invalid request
           content:
@@ -266,6 +281,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ProblemDetails"
+        "500":
+          description: Referenced governance_evidence row failed validation or fingerprint invariant
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GovernanceExportCorruptedEvidenceRow"
   /api/public/verification-reports:
     post:
       operationId: createPublicVerificationReport
@@ -647,14 +668,126 @@ components:
           items:
             type: object
             additionalProperties: true
-    GovernanceAuditBundleV2:
+    GovernanceExportCorruptedEvidenceRow:
       type: object
-      description: Governance export including authoritative lifecycle FSM rows and verification decisions.
-      required: [schemaVersion, generatedAt, userId, workflowId, baseline, events]
+      additionalProperties: false
+      description: Hosted governance export — stored evidence invariant failure.
+      required: [code, evidence_id, message]
+      properties:
+        code:
+          type: string
+          const: CORRUPTED_EVIDENCE_ROW
+        evidence_id:
+          type: string
+          format: uuid
+        message:
+          type: string
+          const: "Stored evidence row failed certificate schema validation or fingerprints do not match stored columns."
+    GovernanceEvidenceFingerprints:
+      type: object
+      additionalProperties: false
+      required: [certificateSha256, materialTruthSha256]
+      properties:
+        certificateSha256:
+          type: string
+        materialTruthSha256:
+          type: string
+    HostedEvidenceExitDecisionV1:
+      type: object
+      additionalProperties: false
+      required: [schemaVersion, exitCode, cliConvention]
       properties:
         schemaVersion:
           type: integer
-          const: 2
+          const: 1
+        exitCode:
+          type: integer
+          minimum: 0
+          maximum: 3
+        cliConvention:
+          type: string
+          const: outcome_certificate_v2
+    HostedDecisionEvidenceCompletenessArtifacts:
+      type: object
+      additionalProperties: false
+      required: [a4Present, a5Present, a5Required]
+      properties:
+        a4Present:
+          type: boolean
+        a5Present:
+          type: boolean
+        a5Required:
+          type: boolean
+    HostedDecisionEvidenceCompleteness:
+      type: object
+      additionalProperties: false
+      required: [status, artifacts]
+      properties:
+        status:
+          type: string
+          enum: [complete, partial, invalid]
+        artifacts:
+          $ref: "#/components/schemas/HostedDecisionEvidenceCompletenessArtifacts"
+    HostedEvidenceSliceV1:
+      type: object
+      additionalProperties: false
+      required:
+        - runId
+        - outcomeCertificate
+        - fingerprints
+        - hostedExit
+        - decisionCompleteness
+        - truthCheckVerdict
+      properties:
+        runId:
+          type: string
+        outcomeCertificate:
+          type: object
+          additionalProperties: true
+          description: Stored Outcome Certificate v3 (schema outcome-certificate-v3).
+        fingerprints:
+          $ref: "#/components/schemas/GovernanceEvidenceFingerprints"
+        hostedExit:
+          $ref: "#/components/schemas/HostedEvidenceExitDecisionV1"
+        decisionCompleteness:
+          $ref: "#/components/schemas/HostedDecisionEvidenceCompleteness"
+        truthCheckVerdict:
+          type: string
+    GovernanceBaselineAcceptedEvidenceV3:
+      type: object
+      additionalProperties: false
+      required: [evidenceSliceKey, runId, fingerprints, runKind]
+      properties:
+        evidenceSliceKey:
+          type: string
+          format: uuid
+        runId:
+          type: string
+        fingerprints:
+          $ref: "#/components/schemas/GovernanceEvidenceFingerprints"
+        runKind:
+          type: string
+    GovernanceAuditBundleV3:
+      type: object
+      additionalProperties: false
+      description: Hosted governance ledger export (breaking; replaces prior schemaVersion 2 governance export payloads).
+      required:
+        - schemaVersion
+        - generatedAt
+        - userId
+        - workflowId
+        - window
+        - lifecycle
+        - fsmTransitions
+        - verificationDecisions
+        - baseline
+        - events
+        - evidenceSlices
+        - baselineAcceptedEvidence
+      properties:
+        schemaVersion:
+          type: integer
+          const: 3
         generatedAt:
           type: string
           format: date-time
@@ -664,6 +797,7 @@ components:
           type: string
         window:
           type: object
+          additionalProperties: false
           required: [from, to]
           properties:
             from:
@@ -695,10 +829,15 @@ components:
           items:
             type: object
             additionalProperties: true
-        decisionEvidenceExport:
+        evidenceSlices:
           type: object
-          additionalProperties: true
-      additionalProperties: true
+          additionalProperties:
+            $ref: "#/components/schemas/HostedEvidenceSliceV1"
+        baselineAcceptedEvidence:
+          nullable: true
+          anyOf:
+            - $ref: "#/components/schemas/GovernanceBaselineAcceptedEvidenceV3"
+            - type: "null"
     ProblemDetails:
       type: object
       required: [type, title, status, detail]

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);
@@ -149,6 +152,7 @@ function buildDiscoveryPayload(root) {
   const integratorGuideSsotRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/integrate.md`;
   const openapiRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/openapi-commercial-v1.yaml`;
   const cursorIntegrationDocRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/cursor-integration.md`;
+  const decisionEvidenceBundleDocRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/docs/decision-evidence-bundle.md`;
   const contractManifestCanonical = `${canonicalOrigin}/contract/v1.json`;
   const contractManifestRaw = `https://raw.githubusercontent.com/${owner}/${repo}/refs/heads/${DISCOVERY_LLM_BRANCH}/schemas/contract/v1.json`;
   const llms = /** @type {{ intentPhrases: string[]; notFor: string[]; relatedQueries: string[] }} */ (
@@ -162,6 +166,7 @@ function buildDiscoveryPayload(root) {
     links: {
       site: `${canonicalOrigin}/`,
       integrate: integrateUrl,
+      runtimeTruthCheckGuide: runtimeTruthCheckGuideUrl,
       learnHub: learnHubUrl,
       openapiCanonical: openapiSelfCanonical,
       openapiRaw,
@@ -171,6 +176,7 @@ function buildDiscoveryPayload(root) {
       llmsBlob,
       integratorGuideSsotRaw,
       cursorIntegrationDocRaw,
+      decisionEvidenceBundleDocRaw,
       contractManifestCanonical,
       contractManifestRaw,
     },
@@ -259,8 +265,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}`,
@@ -268,6 +275,15 @@ function renderLlmsTextFromPayload(payload) {
     `- Verification Contract Manifest (canonical): ${links.contractManifestCanonical}`,
     `- Verification Contract Manifest (repo raw): ${links.contractManifestRaw}`,
     "",
+    "## 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): ${links.decisionEvidenceBundleDocRaw}`,
+    "",
   ];
   const base = lines.join("\n");
   const { appendDiscoveryLlmsAppendix } = require("./discovery-acquisition.lib.cjs");
@@ -289,8 +305,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 */