agentskeptic 5.0.0 → 6.0.1

package/schemas/outcome-certificate-v3.schema.json

@@ -0,0 +1,97 @@
+{
+  "$id": "https://agentskeptic.com/schemas/outcome-certificate-v3.schema.json",
+  "title": "OutcomeCertificateV3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "workflowId",
+    "runKind",
+    "stateRelation",
+    "highStakesReliance",
+    "relianceRationale",
+    "intentSummary",
+    "explanation",
+    "steps",
+    "humanReport",
+    "evidenceCompleteness",
+    "failureSpine"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 3 },
+    "workflowId": { "type": "string", "minLength": 1, "maxLength": 512 },
+    "runKind": {
+      "type": "string",
+      "enum": ["contract_sql", "contract_sql_langgraph_checkpoint_trust", "quick_preview"]
+    },
+    "stateRelation": {
+      "type": "string",
+      "enum": ["matches_expectations", "does_not_match", "not_established"]
+    },
+    "highStakesReliance": { "type": "string", "enum": ["permitted", "prohibited"] },
+    "relianceRationale": { "type": "string", "minLength": 1, "maxLength": 8192 },
+    "intentSummary": { "type": "string", "minLength": 1, "maxLength": 8192 },
+    "explanation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["headline", "details"],
+      "properties": {
+        "headline": { "type": "string", "minLength": 1, "maxLength": 2048 },
+        "details": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["code", "message"],
+            "properties": {
+              "code": { "type": "string", "minLength": 1, "maxLength": 256 },
+              "message": { "type": "string", "minLength": 1, "maxLength": 4096 }
+            }
+          }
+        }
+      }
+    },
+    "steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["seq", "declaredAction", "expectedOutcome", "observedOutcome"],
+        "properties": {
+          "seq": { "type": "integer", "minimum": 0 },
+          "toolId": { "type": "string", "maxLength": 512 },
+          "declaredAction": { "type": "string", "minLength": 1, "maxLength": 4096 },
+          "expectedOutcome": { "type": "string", "minLength": 1, "maxLength": 4096 },
+          "observedOutcome": { "type": "string", "minLength": 1, "maxLength": 8192 }
+        }
+      }
+    },
+    "humanReport": { "type": "string", "minLength": 1, "maxLength": 1048576 },
+    "checkpointVerdicts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["checkpointKey", "verdict", "seqs", "productionMeaning"],
+        "properties": {
+          "checkpointKey": { "type": "string", "minLength": 1, "maxLength": 2048 },
+          "verdict": {
+            "type": "string",
+            "enum": ["verified", "inconsistent", "incomplete"]
+          },
+          "seqs": {
+            "type": "array",
+            "items": { "type": "integer", "minimum": 0 }
+          },
+          "productionMeaning": { "type": "string", "minLength": 1, "maxLength": 8192 }
+        }
+      }
+    },
+    "evidenceCompleteness": {
+      "$ref": "https://agentskeptic.com/schemas/evidence-completeness-v1.schema.json"
+    },
+    "failureSpine": {
+      "$ref": "https://agentskeptic.com/schemas/failure-spine-v1.schema.json"
+    }
+  }
+}

package/schemas/public-verification-report-v3.schema.json

@@ -7,7 +7,7 @@
   "properties": {
     "schemaVersion": { "type": "integer", "const": 3 },
     "certificate": {
-      "$ref": "https://agentskeptic.com/schemas/outcome-certificate-v2.schema.json"
+      "$ref": "https://agentskeptic.com/schemas/outcome-certificate-v3.schema.json"
     },
     "cliVersion": { "type": "string", "maxLength": 128 },
     "createdFrom": { "type": "string", "maxLength": 256 }

package/schemas/regression-artifact-v1.schema.json

@@ -82,7 +82,7 @@
             "enum": ["contract_sql", "contract_sql_langgraph_checkpoint_trust"]
           },
           "certificateCanonicalDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
-          "certificate": { "$ref": "https://agentskeptic.com/schemas/outcome-certificate-v2.schema.json" }
+          "certificate": { "$ref": "https://agentskeptic.com/schemas/outcome-certificate-v3.schema.json" }
         }
       }
     },

package/scripts/discovery-payload.lib.cjs

@@ -27,6 +27,9 @@ const MAX_SUMMARY_UTF8_BYTES = 65536;
 const MAX_PR_BODY_UTF8_BYTES = 10240;
 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 REPO_ROOT = join(__dirname, "..");
 const README_ADOPTION_START = "<!-- adoption-canonical:start -->";
 const README_ADOPTION_END = "<!-- adoption-canonical:end -->";
@@ -311,8 +314,109 @@ function formatStderrBlock(stderrText) {
 }
 
 /**
- * Assemble PR body: header → optional verdict → stderr → footer → marker.
- * Truncates stderr block from the start only until UTF-8 length ≤ max.
+ * Parse workflow stdout for a single-line/single-object Outcome Certificate JSON and extract `failureSpine`.
+ * @param {string} stdoutText
+ * @returns {{ ok: true; spine: Record<string, unknown> } | { malformed: true } | { oversized: true }}
+ */
+function extractFailureSummaryFromStdout(stdoutText) {
+  const t = String(stdoutText ?? "").trim();
+  if (t.length === 0) return { malformed: true };
+  if (utf8ByteLength(t) > MAX_STDOUT_PARSE_BYTES) return { oversized: true };
+  let obj;
+  try {
+    obj = JSON.parse(t);
+  } catch {
+    return { malformed: true };
+  }
+  if (!obj || typeof obj !== "object") return { malformed: true };
+  const spine = obj.failureSpine;
+  if (!spine || typeof spine !== "object") return { malformed: true };
+  return { ok: true, spine };
+}
+
+/**
+ * @param {Record<string, unknown>} spine
+ */
+function renderFailureSummaryMarkdownFromSpine(spine) {
+  const af = /** @type {{ category: string; severity: string; recommendedAction: string; automationSafe: boolean }} */ (
+    spine.actionableFailure
+  );
+  const codes = Array.isArray(spine.primaryCodes) ? spine.primaryCodes.join(",") : "";
+  return [
+    "## Failure summary (agentskeptic)",
+    "",
+    `- trust_decision: ${spine.trustDecision}`,
+    `- summary: ${spine.summary}`,
+    `- actionable_failure: category=${af.category} severity=${af.severity} recommended_action=${af.recommendedAction} automation_safe=${af.automationSafe}`,
+    `- primary_codes: ${codes}`,
+    `- rerun_guidance: ${spine.rerunGuidance}`,
+    `- source: ${spine.source}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * @param {Record<string, unknown>} envelope — cli-error-envelope JSON
+ */
+function projectCliEnvelopeToCiMarkdown(envelope) {
+  const fd = /** @type {{ summary: string; actionableFailure: { category: string; severity: string; recommendedAction: string; automationSafe: boolean } }} */ (
+    envelope.failureDiagnosis
+  );
+  const af = fd.actionableFailure;
+  return [
+    "## Failure summary (agentskeptic)",
+    "",
+    "- trust_decision: unknown",
+    `- summary: ${fd.summary}`,
+    `- actionable_failure: category=${af.category} severity=${af.severity} recommended_action=${af.recommendedAction} automation_safe=${af.automationSafe}`,
+    "- primary_codes: _(operational)_",
+    `- rerun_guidance: ${String(envelope.message)}`,
+    "- source: operational",
+    "",
+  ].join("\n");
+}
+
+/**
+ * @param {string} line
+ */
+function tryParseCliErrorEnvelopeLine(line) {
+  const s = String(line).trim();
+  if (!s.startsWith("{")) return null;
+  try {
+    const o = JSON.parse(s);
+    if (
+      o &&
+      typeof o === "object" &&
+      o.schemaVersion === 2 &&
+      o.kind === "execution_truth_layer_error" &&
+      o.failureDiagnosis &&
+      typeof o.failureDiagnosis === "object" &&
+      o.failureDiagnosis.actionableFailure
+    ) {
+      return o;
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * @param {string} stderrText
+ * @returns {string[]}
+ */
+function extractOperationalFailureMarkdownFromStderr(stderrText) {
+  const out = [];
+  for (const line of String(stderrText).split(/\r?\n/)) {
+    const env = tryParseCliErrorEnvelopeLine(line);
+    if (env) out.push(projectCliEnvelopeToCiMarkdown(env));
+  }
+  return out;
+}
+
+/**
+ * Assemble PR body: header → optional stdout oversize note → failure summary (certificate spine and/or operational stderr) → stderr → footer → marker.
+ * Truncates stderr tail lines from the front until UTF-8 length ≤ max (failure summary retained).
  *
  * @param {Record<string, unknown>} payload
  * @param {{ stderrText: string; workflowStdoutText: string }} capture
@@ -329,12 +433,27 @@ ${String(payload.identityOneLiner)}
 
 `;
 
-  const verdictTrim = String(workflowStdoutText).trim();
-  const oneLine =
-    verdictTrim.length > 0 ? verdictTrim.split("\n")[0].slice(0, 500) : "";
-  const verdictSection = oneLine
-    ? ["## Verification stdout (first line)", "", "```", oneLine, "```", ""].join("\n")
-    : "";
+  const ext = extractFailureSummaryFromStdout(workflowStdoutText);
+  const operationalBlocks = extractOperationalFailureMarkdownFromStderr(stderrText);
+
+  let oversizedNote = "";
+  if (ext.oversized) {
+    oversizedNote = `_(stdout exceeded 262144 UTF-8 bytes; failure summary skipped)_\n\n`;
+  }
+
+  const failureParts = [];
+  if ("ok" in ext && ext.ok) failureParts.push(renderFailureSummaryMarkdownFromSpine(ext.spine));
+  failureParts.push(...operationalBlocks);
+
+  const failureSummaryBlock = failureParts.length > 0 ? failureParts.join("\n") : "";
+
+  let unparsedStdoutBlock = "";
+  if (ext.malformed) {
+    const rawOut = String(workflowStdoutText).trim();
+    if (rawOut.length > 0) {
+      unparsedStdoutBlock = `## Verification stdout (unparsed)\n\n\`\`\`text\n${rawOut}\n\`\`\`\n\n`;
+    }
+  }
 
   let stderrBlock = formatStderrBlock(stderrText);
 
@@ -350,12 +469,16 @@ ${String(payload.identityOneLiner)}
     "",
   ].join("\n");
 
-  function assemble(verdict, sb) {
-    const raw = header + verdict + sb + footer;
+  function assemble(middle) {
+    const raw = header + middle + footer;
     return normalizeDiscoveryText(raw);
   }
 
-  let body = assemble(verdictSection, stderrBlock);
+  function middleFrom(stderrBlk) {
+    return oversizedNote + failureSummaryBlock + unparsedStdoutBlock + stderrBlk;
+  }
+
+  let body = assemble(middleFrom(stderrBlock));
   if (utf8ByteLength(body) <= MAX_PR_BODY_UTF8_BYTES) {
     return body;
   }
@@ -367,19 +490,14 @@ ${String(payload.identityOneLiner)}
     stderrBlock = inner
       ? `## CLI stderr (last ${STDERR_TAIL_LINES} lines)\n\n\`\`\`text\n${inner}\n\`\`\`\n`
       : "## CLI stderr (last 20 lines)\n\n_(no stderr)_\n";
-    body = assemble(verdictSection, stderrBlock);
+    body = assemble(middleFrom(stderrBlock));
     if (utf8ByteLength(body) <= MAX_PR_BODY_UTF8_BYTES) return body;
   }
 
   stderrBlock = "## CLI stderr (last 20 lines)\n\n_(no stderr)_\n";
-  body = assemble(verdictSection, stderrBlock);
+  body = assemble(middleFrom(stderrBlock));
   if (utf8ByteLength(body) <= MAX_PR_BODY_UTF8_BYTES) return body;
 
-  if (verdictSection) {
-    body = assemble("", stderrBlock);
-    if (utf8ByteLength(body) <= MAX_PR_BODY_UTF8_BYTES) return body;
-  }
-
   throw new Error(
     `discovery-payload: PR body still exceeds ${MAX_PR_BODY_UTF8_BYTES} bytes after truncation`,
   );
@@ -408,6 +526,7 @@ module.exports = {
   PR_MARKER_LINE_LEGACY,
   MAX_SUMMARY_UTF8_BYTES,
   MAX_PR_BODY_UTF8_BYTES,
+  MAX_STDOUT_PARSE_BYTES,
   STDERR_TAIL_LINES,
   buildDiscoveryPayload,
   normalizeDiscoveryText,
@@ -417,6 +536,9 @@ module.exports = {
   renderLlmsTextFromPayload,
   renderCiSummaryMarkdownFromPayload,
   renderCiPrBodyFromPayload,
+  extractFailureSummaryFromStdout,
+  renderFailureSummaryMarkdownFromSpine,
+  projectCliEnvelopeToCiMarkdown,
   parseGithubRepoFromUrl,
   selectPrCommentUpsert,
 };

package/scripts/emit-primary-marketing.cjs

@@ -178,6 +178,42 @@ Normative **public distribution** and anchor sync: [\`docs/public-distribution.m
 - Verification Contract Manifest (repo raw): ${contractRaw}
 - Acquisition page (canonical): ${acquisitionUrl}
 - CI regeneration + drift pathspecs: [\`schemas/ci/verification-truth.manifest.json\`](schemas/ci/verification-truth.manifest.json) (validated by [\`test/verification-truth.closed-drift.contract.test.mjs\`](test/verification-truth.closed-drift.contract.test.mjs))
+
+## Cursor Cloud specific instructions
+
+### Architecture
+
+This is an npm workspace monorepo with two packages:
+- **Root** (\`agentskeptic\`): Core verification library + CLI. Framework-agnostic Node.js, ESM, TypeScript.
+- **\`website/\`** (\`agentskeptic-web\`): Next.js 16 commercial SaaS app (Auth, Stripe, API keys, verification demo).
+
+### Prerequisites
+
+- **Node.js 22.x** (required by \`engines\` field). Install via nvm: \`nvm install 22\`.
+- **PostgreSQL 16** with two databases: \`wfv_website\` (core) and \`wfv_telemetry\` (telemetry).
+- The env file at \`website/.env\` (gitignored) must have \`DATABASE_URL\` and \`TELEMETRY_DATABASE_URL\` pointing to local Postgres. See \`website/.env.example\` for all variables.
+
+### Common commands
+
+| Task | Command | Notes |
+|------|---------|-------|
+| Install deps | \`npm install\` (repo root) | Installs root + website workspace |
+| Build core | \`npm run build\` | TypeScript compile + asset generation |
+| Run demo | \`npm start\` | Builds then runs bundled wf_complete/wf_missing verification |
+| Website dev | \`npm run dev\` (repo root) | Delegates to \`next dev --turbopack\` in website workspace |
+| Core vitest | \`npx vitest run\` (repo root) | Runs \`src/**/*.test.ts\` and \`test/**/*.test.ts\` |
+| SQLite tests | \`npm run test:node:sqlite\` | Builds first, then runs node:test suite (fast, no Postgres) |
+| Website vitest | \`npm run test:vitest -w agentskeptic-web\` | Needs \`DATABASE_URL\` + \`TELEMETRY_DATABASE_URL\` |
+| Full CI gate | \`npm test\` (or \`npm run verification:truth\`) | Requires Postgres; see \`docs/testing.md\` |
+| DB migrate | \`npm run db:migrate\` / \`npm run db:migrate:telemetry\` (from \`website/\`) | Requires \`DATABASE_URL\`/\`TELEMETRY_DATABASE_URL\` in env or \`website/.env\` |
+
+### Gotchas
+
+- \`npm run build\` must complete before the CLI (\`node dist/cli.js\`) or website demo API (\`/api/verify\`) work.
+- The website migration scripts (\`db-migrate.mjs\`) load \`website/.env\` but only for keys not already in \`process.env\`. If env vars are not exported in the shell, the \`.env\` file must exist.
+- The commit hook (\`.husky/commit-msg\`) runs \`commitlint\` for Conventional Commits. Use \`--no-verify\` to skip if needed, but CI enforces the same rules on PRs.
+- PostgreSQL must be running before migrations or website dev. Start with: \`pg_ctlcluster 16 main start\`.
+- \`src/planTransition.test.ts\` has a known timeout-sensitive integration test that may flake in resource-constrained environments. This is pre-existing, not a setup issue.
 `;
   writeFileSync(join(ROOT, "AGENTS.md"), body, "utf8");
 }