stilltrue 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# stilltrue
+
+> Your tests check your code. **stilltrue** checks your facts.
+
+AI-in-the-loop apps quietly start lying three ways: code changes break old
+answers, the world changes and curated facts rot, and the model embellishes
+beyond its sources. stilltrue is one watchdog per failure mode, run from CI —
+no server, no dashboard, no SaaS.
+
+| Command | Watchdog | Status |
+|---|---|---|
+| `npx stilltrue drift` | Curated facts vs their live authoritative sources — fails the build on rot | **v0.1 focus** |
+| `npx stilltrue golden` | Deterministic regression evals for answers | later (may wrap promptfoo) |
+| `verify` (library) | Judge answers against their sources in the request path | later (P9-shaped staged pipeline) |
+
+**Why drift first:** "drift detection" in the market means statistical ML
+feature drift; website-change monitors alert humans, not CI. Nobody ships
+*"assert my curated facts still match their live source, as a CI check."*
+This was built bespoke three times across three domains before becoming a
+package — see [docs/BRIEF.md](docs/BRIEF.md) for the full design brief,
+positioning, and build plan.
+
+## Core principle
+
+**AI may extract, but must never decide.** The default drift path has zero AI:
+fetch → parse → compare → diff. A consumer's `source()` may use an LLM to pull
+structure out of a messy page, but the comparison and the verdict are always
+deterministic. Same inputs, same verdict — a nondeterministic alarm trains
+people to ignore it.
+
+Drift has three outcomes, never two: `pass`, `rot` (facts changed — fail the
+build), and `error` (source unreachable — warn, don't fail). Conflating the
+last two causes alarm fatigue.
+
+## Status
+
+Pre-v0.1. Current state: config seam design (`src/config.ts`) validated
+against two real production checks (`examples/stilltrue.config.ts`). Next:
+the drift runner, then swapping AskGwinnett's bespoke GitHub Actions to it.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * npx stilltrue drift   — run drift checks (v0.1 scope)
+ * npx stilltrue golden  — regression evals (later)
+ * npx stilltrue report  — HTML drift report (later)
+ */
+const [command] = process.argv.slice(2);
+switch (command) {
+    case 'drift':
+        console.error('stilltrue drift: not implemented yet — see docs/BRIEF.md, First session §3');
+        process.exit(1);
+    case undefined:
+        console.log('usage: stilltrue <drift|golden|report>');
+        process.exit(1);
+    default:
+        console.error(`stilltrue: unknown command "${command}"`);
+        process.exit(1);
+}
+export {};

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The config seam — the entire product is "the package owns the *how*,
+ * the consumer's config owns the *what*." (docs/BRIEF.md, First session §2)
+ *
+ * Designed against two real checks before the runner exists:
+ * see examples/stilltrue.config.ts (GCPS board roster + BOC refresh).
+ */
+/** What a drift check found. Three outcomes, never two (BRIEF §First session 4). */
+export type DriftOutcome = 
+/** Live source still matches the expected file. */
+'pass'
+/** Facts no longer match — fail the build. A human fixes. */
+ | 'rot'
+/** Source unreachable / timeout / WAF 403 — warn loudly, do NOT fail. */
+ | 'error';
+export interface DriftResult {
+    name: string;
+    outcome: DriftOutcome;
+    /** Human-readable detail: the diff for `rot`, the cause for `error`. */
+    messages: string[];
+    /** Structured diff when outcome is `rot`, for the HTML report. */
+    diff?: {
+        expected: unknown;
+        actual: unknown;
+    };
+    checkedAt: string;
+}
+/**
+ * One curated fact vs its live authoritative source.
+ *
+ * `source()` is the consumer's code — it may fetch+parse deterministically
+ * or use an LLM to extract structure from a messy page; the package neither
+ * knows nor cares. The comparison stays deterministic either way.
+ */
+export interface DriftCheck<T = unknown> {
+    name: string;
+    /** Fetch the live source and return structured data. Throw => `error`, never `rot`. */
+    source: () => Promise<T>;
+    /** Path to the curated expected file (JSON), or the expected value itself. */
+    expect: string | T;
+    /**
+     * How to compare. A named built-in ('deep-equal', 'surnames', ...) or a
+     * custom deterministic function returning mismatch messages ([] = pass).
+     */
+    compare?: string | ((expected: T, actual: T) => string[]);
+}
+export interface StilltrueConfig {
+    drift?: DriftCheck<any>[];
+    /** golden and verify are later phases — see docs/BRIEF.md build plan. */
+    golden?: unknown;
+    verify?: unknown;
+}
+/** Identity function for typed configs: `export default defineStilltrue({...})`. */
+export declare function defineStilltrue(config: StilltrueConfig): StilltrueConfig;

package/dist/config.js

@@ -0,0 +1,11 @@
+/**
+ * The config seam — the entire product is "the package owns the *how*,
+ * the consumer's config owns the *what*." (docs/BRIEF.md, First session §2)
+ *
+ * Designed against two real checks before the runner exists:
+ * see examples/stilltrue.config.ts (GCPS board roster + BOC refresh).
+ */
+/** Identity function for typed configs: `export default defineStilltrue({...})`. */
+export function defineStilltrue(config) {
+    return config;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { defineStilltrue, type StilltrueConfig, type DriftCheck, type DriftResult, type DriftOutcome, } from './config.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { defineStilltrue, } from './config.js';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "stilltrue",
+  "version": "0.0.1",
+  "description": "Your tests check your code. stilltrue checks your facts. CI checks for AI-in-the-loop apps: drift (curated facts vs live sources), golden (regression evals), verify (judge answers against sources).",
+  "keywords": [
+    "drift",
+    "facts",
+    "eval",
+    "llm",
+    "ci",
+    "regression",
+    "groundedness"
+  ],
+  "license": "MIT",
+  "author": "Brian Foster",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "stilltrue": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test --experimental-strip-types test/*.test.ts"
+  },
+  "dependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}