agentskeptic 0.1.3 → 0.1.5

package/README.md

@@ -7,7 +7,9 @@
 
 AgentSkeptic answers with read-only SQL at verification time—not with trace success flags or chat narratives.
 
-Teams ship agent and automation workflows where traces, tool responses, and success flags look green while the database row is missing, stale, or wrong. AgentSkeptic closes that gap by comparing structured tool activity to read-only SQL against your SQLite or Postgres at verification time: it tells you whether observed state matched expectations derived from what the workflow claimed—not whether a step narrative sounded successful. It is a snapshot check, not proof of causality or execution.
+Teams ship agent and automation workflows where traces, tool responses, and success flags look green while the database row is missing, stale, or wrong. AgentSkeptic compares structured tool activity to read-only SQL against your SQLite or Postgres at verification time and reports whether observed state matched expectations derived from what the workflow claimed—not whether the step narrative read as successful.
+
+Use it when you need persisted rows checked against declared tool parameters at verification time before customer-facing actions, compliance evidence, or CI gates.
 
 ### Pasteable terminal proof (bundled demo)
 
@@ -50,7 +52,7 @@ steps:
 }
 ```
 
-[Why traces are not database truth](https://agentskeptic.com/database-truth-vs-traces)
+[Database truth vs traces](https://agentskeptic.com/database-truth-vs-traces)
 <!-- discovery-acquisition-fold:end -->
 
 **One-sentence value:** Read-only SQL checks that your database **at verification time** matches **expectations derived from structured tool activity**—not whether a trace step “succeeded.”

package/dist/discovery-payload-v1.json

@@ -14,7 +14,7 @@
   },
   "appendix": {
     "slug": "/database-truth-vs-traces",
-    "visitorProblemAnswer": "Teams ship agent and automation workflows where traces, tool responses, and success flags look green while the database row is missing, stale, or wrong. AgentSkeptic closes that gap by comparing structured tool activity to read-only SQL against your SQLite or Postgres at verification time: it tells you whether observed state matched expectations derived from what the workflow claimed—not whether a step narrative sounded successful. It is a snapshot check, not proof of causality or execution.",
+    "visitorProblemAnswer": "Teams ship agent and automation workflows where traces, tool responses, and success flags look green while the database row is missing, stale, or wrong. AgentSkeptic compares structured tool activity to read-only SQL against your SQLite or Postgres at verification time and reports whether observed state matched expectations derived from what the workflow claimed—not whether the step narrative read as successful.\n\nUse it when you need persisted rows checked against declared tool parameters at verification time before customer-facing actions, compliance evidence, or CI gates.",
     "intentPhrases": [
       "green trace wrong database row agent workflow",
       "trace says success but CRM row missing",
@@ -38,7 +38,12 @@
       "Green LangGraph or agent trace but wrong or missing Postgres row",
       "OpenAI-style tool loop reported success; CRM or SQLite state does not match",
       "CI passed on workflow logs; database side effect never showed up",
-      "Need a gate before production: read-only verification, not more log volume"
+      "Need a gate before production: read-only verification, not more log volume",
+      "Green dashboards still happen when an AI agent writes wrong CRM data and you need read-only SQL before you trust the row.",
+      "When automation reports success while database records disagree with declared tool parameters until read-only verification, treat trace color as non-authoritative.",
+      "Debugging Postgres after a LangGraph run requires row-level truth at verification time beyond trace completion flags alone for customer-facing data.",
+      "When a Stripe webhook returns OK you still need the ledger database row to match before finance treats settlement as final and read-only SQL verifies persisted state.",
+      "CI can stay green on workflow logs while the database side effect is missing until a read-only gate surfaces ROW_ABSENT before production."
     ],
     "indexableGuides": [
       {
@@ -65,6 +70,45 @@
         "path": "/guides/pre-production-read-only-sql-gate",
         "navLabel": "Pre-production read-only SQL gate",
         "problemAnchor": "Need a gate before production: read-only verification, not more log volume"
+      },
+      {
+        "path": "/guides/ai-agent-wrong-crm-data",
+        "navLabel": "AI agent wrong CRM data read-only check",
+        "problemAnchor": "Green dashboards still happen when an AI agent writes wrong CRM data"
+      },
+      {
+        "path": "/guides/automation-success-database-mismatch",
+        "navLabel": "Automation success vs database mismatch",
+        "problemAnchor": "When automation reports success while database records disagree with declared tool parameters until read-only verification"
+      },
+      {
+        "path": "/guides/debug-postgres-after-langgraph",
+        "navLabel": "Debug Postgres after LangGraph runs",
+        "problemAnchor": "Debugging Postgres after a LangGraph run requires row-level truth at verification time beyond trace completion flags alone"
+      },
+      {
+        "path": "/guides/stripe-webhook-database-alignment",
+        "navLabel": "Stripe webhook OK vs database alignment",
+        "problemAnchor": "When a Stripe webhook returns OK you still need the ledger database row to match before finance treats settlement as final"
+      },
+      {
+        "path": "/guides/ci-green-missing-database-side-effect",
+        "navLabel": "CI green but missing database side effect",
+        "problemAnchor": "CI can stay green on workflow logs while the database side effect is missing until a read-only gate surfaces ROW_ABSENT before production"
+      }
+    ],
+    "indexableExamples": [
+      {
+        "path": "/examples/wf-complete",
+        "navLabel": "Bundled verified workflow (wf_complete)",
+        "problemAnchor": "Bundled wf_complete demo: read-only SQL matched the expected contacts row under the packaged registry at verification time.",
+        "embedKey": "wf_complete"
+      },
+      {
+        "path": "/examples/wf-missing",
+        "navLabel": "Bundled inconsistent workflow (wf_missing)",
+        "problemAnchor": "Bundled wf_missing demo: ROW_ABSENT when structured tool activity implied a row read-only SQL did not find at verification time.",
+        "embedKey": "wf_missing"
       }
     ],
     "shareableTerminalDemo": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentskeptic",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Green agent traces and tool success flags often hide missing or wrong database rows. AgentSkeptic runs read-only SQL at verification time against persisted state vs structured tool activity—not chat narratives.",
   "license": "MIT",
   "type": "module",
@@ -38,6 +38,7 @@
     "sync:public-product-anchors": "node scripts/public-product-anchors.cjs",
     "distribution:consumer-pipeline": "node scripts/distribution-consumer-pipeline.mjs",
     "check:discovery-acquisition": "node scripts/validate-discovery-acquisition.mjs",
+    "verify:web-marketing-copy": "node scripts/validate-discovery-acquisition.mjs && node --test test/visitor-problem-outcome.test.mjs && npm run build -w agentskeptic-web && node scripts/run-website-vitest-with-reuse.mjs",
     "check:public-product-anchors": "node scripts/public-product-anchors.cjs --check",
     "test:commercial-layer": "node scripts/validate-commercial-funnel.mjs",
     "build:website": "npm run build && npm run build -w agentskeptic-web",

package/scripts/discovery-acquisition.lib.cjs

@@ -117,6 +117,39 @@ function validateIndexableGuides(discovery) {
   }
 }
 
+/**
+ * @param {Record<string, unknown>} discovery
+ */
+function validateIndexableExamples(discovery) {
+  const ex = /** @type {{ path: string; navLabel: string; problemAnchor: string; embedKey: string }[]} */ (
+    discovery.indexableExamples
+  );
+  if (!Array.isArray(ex)) {
+    throw new Error("discovery-acquisition: indexableExamples must be an array");
+  }
+  if (ex.length !== 2) {
+    throw new Error("discovery-acquisition: indexableExamples must have length exactly 2");
+  }
+  if (ex[0].path !== "/examples/wf-complete" || ex[1].path !== "/examples/wf-missing") {
+    throw new Error(
+      "discovery-acquisition: indexableExamples paths must be /examples/wf-complete then /examples/wf-missing",
+    );
+  }
+  if (ex[0].embedKey !== "wf_complete" || ex[1].embedKey !== "wf_missing") {
+    throw new Error(
+      "discovery-acquisition: indexableExamples embedKey order must be wf_complete then wf_missing",
+    );
+  }
+  for (let i = 0; i < ex.length; i++) {
+    const row = ex[i];
+    const nl = String(row.navLabel);
+    const pa = String(row.problemAnchor);
+    if (nl.includes("`") || pa.includes("`")) {
+      throw new Error(`discovery-acquisition: indexableExamples[${i}] must not contain backtick`);
+    }
+  }
+}
+
 /**
  * @param {string} baseLlms
  * @param {Record<string, unknown>} discovery
@@ -136,6 +169,13 @@ function appendDiscoveryLlmsAppendix(baseLlms, discovery, canonicalOrigin) {
       out += `- ${origin}${String(g.path)}\n`;
     }
   }
+  const examples = /** @type {{ path: string }[] | undefined} */ (discovery.indexableExamples);
+  if (Array.isArray(examples) && examples.length > 0) {
+    out += "\n## Indexable examples\n";
+    for (const ex of examples) {
+      out += `- ${origin}${String(ex.path)}\n`;
+    }
+  }
   const demo = discovery.shareableTerminalDemo;
   if (demo && typeof demo.title === "string" && typeof demo.transcript === "string") {
     out += `\n## ${demo.title}\n\n\`\`\`text\n${demo.transcript}\n\`\`\`\n`;
@@ -182,6 +222,7 @@ function validateDiscoveryAcquisition(root) {
     );
   }
   validateIndexableGuides(discovery);
+  validateIndexableExamples(discovery);
   return discovery;
 }
 
@@ -191,5 +232,6 @@ module.exports = {
   appendDiscoveryLlmsAppendix,
   validateDiscoveryAcquisition,
   validateIndexableGuides,
+  validateIndexableExamples,
   discoveryPaths,
 };

package/scripts/discovery-payload.lib.cjs

@@ -125,6 +125,7 @@ function buildDiscoveryPayload(root) {
       relatedQueries: llms.relatedQueries.map(String),
       demandMoments: /** @type {string[]} */ (discovery.demandMoments).map(String),
       indexableGuides: /** @type {unknown} */ (discovery.indexableGuides),
+      indexableExamples: /** @type {unknown} */ (discovery.indexableExamples),
       shareableTerminalDemo: {
         title: String(demo.title),
         transcript: String(demo.transcript),
@@ -137,7 +138,7 @@ function buildDiscoveryPayload(root) {
  * @param {Record<string, unknown>} payload
  */
 function discoveryObjectFromAppendix(payload) {
-  const ap = /** @type {{ slug: string; visitorProblemAnswer: string; intentPhrases: string[]; notFor: string[]; relatedQueries: string[]; demandMoments: string[]; indexableGuides?: { path: string; navLabel: string; problemAnchor: string }[]; shareableTerminalDemo?: { title: string; transcript: string } }} */ (
+  const ap = /** @type {{ slug: string; visitorProblemAnswer: string; intentPhrases: string[]; notFor: string[]; relatedQueries: string[]; demandMoments: string[]; indexableGuides?: { path: string; navLabel: string; problemAnchor: string }[]; indexableExamples?: { path: string; navLabel: string; problemAnchor: string; embedKey: string }[]; shareableTerminalDemo?: { title: string; transcript: string } }} */ (
     payload.appendix
   );
   const out = {
@@ -156,6 +157,9 @@ function discoveryObjectFromAppendix(payload) {
   if (Array.isArray(ap.indexableGuides)) {
     Object.assign(out, { indexableGuides: ap.indexableGuides });
   }
+  if (Array.isArray(ap.indexableExamples)) {
+    Object.assign(out, { indexableExamples: ap.indexableExamples });
+  }
   return out;
 }