@imix-js/taproot 0.3.0 → 0.5.0

package/dist/core/test-cache.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs';
+import { join, resolve, relative, dirname } from 'path';
+import { spawn } from 'child_process';
+import { readResolutions } from './dod-runner.js';
+const DEFAULT_TEST_TIMEOUT_MS = 300_000; // 300 seconds
+const DEFAULT_MAX_AGE_MS = 60 * 60 * 1000; // 60 minutes
+/** Derive the cache path from an impl.md path.
+ *  Strips 'taproot/' prefix and '/impl.md' suffix, maps into .taproot/.test-results/.
+ *  Handles both absolute and relative implPath inputs. */
+export function deriveCachePath(implPath, cwd) {
+    const absImpl = resolve(cwd, implPath);
+    const relImpl = relative(cwd, absImpl).replace(/\\/g, '/');
+    // Strip leading 'taproot/' segment
+    const withoutRoot = relImpl.startsWith('taproot/')
+        ? relImpl.slice('taproot/'.length)
+        : relImpl;
+    // Strip trailing '/impl.md'
+    const key = withoutRoot.endsWith('/impl.md')
+        ? withoutRoot.slice(0, -'/impl.md'.length)
+        : withoutRoot;
+    return join(cwd, '.taproot', '.test-results', `${key}.json`);
+}
+/** Read a cached test result. Returns null if absent or malformed. */
+export function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const raw = readFileSync(cachePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.exitCode !== 'number' || !parsed.timestamp)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true if the cached result is malformed JSON (exists but unparseable). */
+export function isCacheCorrupt(cachePath) {
+    if (!existsSync(cachePath))
+        return false;
+    try {
+        JSON.parse(readFileSync(cachePath, 'utf-8'));
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/** Check whether a cached result is stale.
+ *  Stale if: any tracked source file is newer than the cache timestamp,
+ *  or (if no source files listed) the cache is older than testResultMaxAge. */
+export function isCacheStale(cache, implPath, cwd, testResultMaxAgeMs = DEFAULT_MAX_AGE_MS) {
+    const absImpl = resolve(cwd, implPath);
+    const cacheTs = Date.parse(cache.timestamp);
+    if (isNaN(cacheTs))
+        return true;
+    // Read source files from impl.md
+    const sourceFiles = readSourceFiles(absImpl, cwd);
+    if (sourceFiles.length === 0) {
+        // Fall back to max-age check
+        return Date.now() - cacheTs > testResultMaxAgeMs;
+    }
+    // Stale if any source file is newer than the cache
+    for (const src of sourceFiles) {
+        const absSrc = resolve(cwd, src);
+        if (!existsSync(absSrc))
+            continue;
+        try {
+            const mtime = statSync(absSrc).mtimeMs;
+            if (mtime > cacheTs)
+                return true;
+        }
+        catch {
+            // ignore stat errors
+        }
+    }
+    return false;
+}
+function readSourceFiles(absImplPath, cwd) {
+    try {
+        const content = readFileSync(absImplPath, 'utf-8');
+        const match = content.match(/^## Source Files\s*\n([\s\S]*?)(?=\n## |\n$|$)/m);
+        if (!match)
+            return [];
+        const sources = [];
+        for (const m of match[1].matchAll(/`([^`]+)`/g)) {
+            sources.push(m[1]);
+        }
+        return sources;
+    }
+    catch {
+        return [];
+    }
+}
+/** Write a test result to the cache file, creating parent dirs as needed. */
+export function writeCache(cachePath, result) {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify(result, null, 2), 'utf-8');
+}
+/** Execute testsCommand, streaming output to the terminal while also capturing it.
+ *  Returns the TestResult with the last N lines as summary. */
+export async function executeTestCommand(command, cwd, timeoutMs = DEFAULT_TEST_TIMEOUT_MS) {
+    return new Promise((resolvePromise) => {
+        const timestamp = new Date().toISOString();
+        const lines = [];
+        const child = spawn(command, { shell: true, cwd });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        function handleData(chunk, stream) {
+            const text = chunk.toString();
+            stream.write(text);
+            lines.push(...text.split('\n'));
+        }
+        child.stdout?.on('data', (chunk) => handleData(chunk, process.stdout));
+        child.stderr?.on('data', (chunk) => handleData(chunk, process.stderr));
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const exitCode = timedOut ? -1 : (code ?? 1);
+            const timeoutSecs = Math.round(timeoutMs / 1000);
+            const summaryLines = timedOut
+                ? [`timed out after ${timeoutSecs}s`]
+                : lines.filter(l => l.trim()).slice(-20);
+            resolvePromise({
+                timestamp,
+                command,
+                exitCode,
+                summary: summaryLines.join('\n'),
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolvePromise({
+                timestamp,
+                command,
+                exitCode: 127,
+                summary: err.message,
+            });
+        });
+    });
+}
+/** Full evidence-backed tests-passing check.
+ *  Returns { passed, output, correction, warnNoCache } */
+export async function runTestsPassingWithCache(options) {
+    const { implPath, cwd, testsCommand, rerunTests } = options;
+    const testResultMaxAgeMs = options.testResultMaxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const testTimeoutMs = options.testTimeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
+    const cachePath = deriveCachePath(implPath, cwd);
+    // Warn and re-run if cache is corrupt
+    if (isCacheCorrupt(cachePath)) {
+        process.stderr.write(`Warning: Ignoring malformed cache at ${cachePath} — re-running tests.\n`);
+    }
+    let result = null;
+    if (!rerunTests) {
+        result = readCache(cachePath);
+        if (result && isCacheStale(result, implPath, cwd, testResultMaxAgeMs)) {
+            result = null; // stale — will re-execute
+        }
+    }
+    // Execute if no fresh cache
+    if (!result) {
+        result = await executeTestCommand(testsCommand, cwd, testTimeoutMs);
+        writeCache(cachePath, result);
+    }
+    if (result.exitCode === 0) {
+        return { passed: true, output: '', correction: '' };
+    }
+    if (result.exitCode === -1) {
+        const timeoutSecs = Math.round(testTimeoutMs / 1000);
+        return {
+            passed: false,
+            output: result.summary,
+            correction: `tests-passing blocked: test command timed out after ${timeoutSecs}s. Increase testTimeout in .taproot/settings.yaml if needed.`,
+        };
+    }
+    return {
+        passed: false,
+        output: result.summary,
+        correction: 'tests-passing blocked: Fix failing tests and re-run taproot dod.',
+    };
+}
+// Re-export for use in commithook staleness check
+export { readResolutions };
+//# sourceMappingURL=test-cache.js.map

package/dist/core/test-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-cache.js","sourceRoot":"","sources":["../../src/core/test-cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC;AAClF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AASlD,MAAM,uBAAuB,GAAG,OAAO,CAAC,CAAC,cAAc;AACvD,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AAExD;;0DAE0D;AAC1D,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,GAAW;IAC3D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE3D,mCAAmC;IACnC,MAAM,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC;QAChD,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;QAClC,CAAC,CAAC,OAAO,CAAC;IAEZ,4BAA4B;IAC5B,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC1C,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAC1C,CAAC,CAAC,WAAW,CAAC;IAEhB,OAAO,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,SAAiB;IACzC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;QAC7C,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAC1E,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IACzC,IAAI,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;QAC7C,OAAO,KAAK,CAAC;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;+EAE+E;AAC/E,MAAM,UAAU,YAAY,CAC1B,KAAiB,EACjB,QAAgB,EAChB,GAAW,EACX,qBAA6B,kBAAkB;IAE/C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAEhC,iCAAiC;IACjC,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAElD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,6BAA6B;QAC7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,kBAAkB,CAAC;IACnD,CAAC;IAED,mDAAmD;IACnD,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC;YACvC,IAAI,KAAK,GAAG,OAAO;gBAAE,OAAO,IAAI,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,qBAAqB;QACvB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,WAAmB,EAAE,GAAW;IACvD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QAC/E,IAAI,CAAC,KAAK;YAAE,OAAO,EAAE,CAAC;QACtB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC,CAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YACjD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,MAAkB;IAC9D,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC;AAED;+DAC+D;AAC/D,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAe,EACf,GAAW,EACX,YAAoB,uBAAuB;IAE3C,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QAEnD,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,CAAC,IAAI,EAAE,CAAC;QACf,CAAC,EAAE,SAAS,CAAC,CAAC;QAEd,SAAS,UAAU,CAAC,KAAa,EAAE,MAA0B;YAC3D,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;YAC9B,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAClC,CAAC;QAED,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/E,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAE/E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;YAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;YACjD,MAAM,YAAY,GAAG,QAAQ;gBAC3B,CAAC,CAAC,CAAC,mBAAmB,WAAW,GAAG,CAAC;gBACrC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;YAE3C,cAAc,CAAC;gBACb,SAAS;gBACT,OAAO;gBACP,QAAQ;gBACR,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;aACjC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,cAAc,CAAC;gBACb,SAAS;gBACT,OAAO;gBACP,QAAQ,EAAE,GAAG;gBACb,OAAO,EAAE,GAAG,CAAC,OAAO;aACrB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;0DAC0D;AAC1D,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAO9C;IACC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC5D,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,kBAAkB,CAAC;IAC5E,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;IACvE,MAAM,SAAS,GAAG,eAAe,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAEjD,sCAAsC;IACtC,IAAI,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wCAAwC,SAAS,wBAAwB,CAC1E,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,GAAsB,IAAI,CAAC;IAErC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,MAAM,IAAI,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,kBAAkB,CAAC,EAAE,CAAC;YACtE,MAAM,GAAG,IAAI,CAAC,CAAC,0BAA0B;QAC3C,CAAC;IACH,CAAC;IAED,4BAA4B;IAC5B,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,MAAM,kBAAkB,CAAC,YAAY,EAAE,GAAG,EAAE,aAAa,CAAC,CAAC;QACpE,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACtD,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;QACrD,OAAO;YACL,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,MAAM,CAAC,OAAO;YACtB,UAAU,EAAE,uDAAuD,WAAW,8DAA8D;SAC7I,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,MAAM,CAAC,OAAO;QACtB,UAAU,EAAE,kEAAkE;KAC/E,CAAC;AACJ,CAAC;AAED,kDAAkD;AAClD,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/core/truth-checker.d.ts

@@ -0,0 +1,45 @@
+export type TruthScope = 'intent' | 'behaviour' | 'impl';
+export type DocLevel = 'intent' | 'behaviour' | 'impl';
+export interface TruthFile {
+    relPath: string;
+    scope: TruthScope;
+    ambiguous: boolean;
+    unreadable: boolean;
+    content: string;
+}
+/**
+ * Determine scope from a path relative to the global-truths directory.
+ * Sub-folder takes precedence over suffix when they conflict (most restrictive wins).
+ */
+export declare function resolveTruthScope(relFromGT: string): {
+    scope: TruthScope;
+    ambiguous: boolean;
+};
+/** Does a truth at scope X apply to a document at level Y? */
+export declare function scopeAppliesTo(truthScope: TruthScope, docLevel: DocLevel): boolean;
+/** Returns the absolute path to global-truths/, or null if it doesn't exist. */
+export declare function globalTruthsDir(cwd: string): string | null;
+/** Get hierarchy level of a file based on its filename. */
+export declare function docLevelFromFilename(filename: string): DocLevel | null;
+/** Collect all truth files applicable to the given document level. Skips README.md. */
+export declare function collectApplicableTruths(cwd: string, docLevel: DocLevel): TruthFile[];
+/**
+ * Write a truth-check session marker after the agent has approved the truth check.
+ * Called by `taproot truth-sign`.
+ */
+export declare function writeTruthSession(cwd: string, stagedDocs: Array<{
+    path: string;
+    content: string;
+}>, truths: TruthFile[]): void;
+export interface SessionValidation {
+    valid: boolean;
+    reason: string;
+}
+/**
+ * Validate that a truth-check session exists and matches the current staging state.
+ * Called by the pre-commit hook.
+ */
+export declare function validateTruthSession(cwd: string, stagedDocs: Array<{
+    path: string;
+    content: string;
+}>, truths: TruthFile[]): SessionValidation;

package/dist/core/truth-checker.js

@@ -0,0 +1,152 @@
+import { createHash } from 'crypto';
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname, basename, relative } from 'path';
+const SCOPES = ['intent', 'behaviour', 'impl'];
+/**
+ * Determine scope from a path relative to the global-truths directory.
+ * Sub-folder takes precedence over suffix when they conflict (most restrictive wins).
+ */
+export function resolveTruthScope(relFromGT) {
+    const normalised = relFromGT.replace(/\\/g, '/');
+    const parts = normalised.split('/');
+    const filename = parts[parts.length - 1];
+    const topFolder = parts.length > 1 ? parts[0] : null;
+    const suffixMatch = filename.match(/_(intent|behaviour|impl)\.md$/);
+    const suffixScope = suffixMatch?.[1];
+    const folderScope = topFolder && SCOPES.includes(topFolder)
+        ? topFolder
+        : null;
+    // Conflicting signals: sub-folder wins (most restrictive)
+    if (folderScope && suffixScope && folderScope !== suffixScope) {
+        return { scope: folderScope, ambiguous: false };
+    }
+    if (folderScope)
+        return { scope: folderScope, ambiguous: false };
+    if (suffixScope)
+        return { scope: suffixScope, ambiguous: false };
+    // No scope signal — default to intent (broadest)
+    return { scope: 'intent', ambiguous: true };
+}
+/** Does a truth at scope X apply to a document at level Y? */
+export function scopeAppliesTo(truthScope, docLevel) {
+    if (truthScope === 'intent')
+        return true;
+    if (truthScope === 'behaviour')
+        return docLevel === 'behaviour' || docLevel === 'impl';
+    return docLevel === 'impl'; // impl scope — impl only
+}
+const GLOBAL_TRUTHS_SUBDIR = 'taproot/global-truths';
+/** Returns the absolute path to global-truths/, or null if it doesn't exist. */
+export function globalTruthsDir(cwd) {
+    const dir = join(cwd, GLOBAL_TRUTHS_SUBDIR);
+    return existsSync(dir) ? dir : null;
+}
+/** Get hierarchy level of a file based on its filename. */
+export function docLevelFromFilename(filename) {
+    const name = basename(filename);
+    if (name === 'intent.md')
+        return 'intent';
+    if (name === 'usecase.md')
+        return 'behaviour';
+    if (name === 'impl.md')
+        return 'impl';
+    return null;
+}
+/** Collect all truth files applicable to the given document level. Skips README.md. */
+export function collectApplicableTruths(cwd, docLevel) {
+    const dir = globalTruthsDir(cwd);
+    if (!dir)
+        return [];
+    const results = [];
+    function walk(currentDir, relFromGT) {
+        let entries;
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry.name);
+            const childRel = relFromGT ? `${relFromGT}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                walk(fullPath, childRel);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md') {
+                const { scope, ambiguous } = resolveTruthScope(childRel);
+                if (!scopeAppliesTo(scope, docLevel))
+                    continue;
+                let content = '';
+                let unreadable = false;
+                try {
+                    content = readFileSync(fullPath, 'utf-8');
+                }
+                catch {
+                    unreadable = true;
+                }
+                results.push({
+                    relPath: relative(cwd, fullPath).replace(/\\/g, '/'),
+                    scope,
+                    ambiguous,
+                    unreadable,
+                    content,
+                });
+            }
+        }
+    }
+    walk(dir, '');
+    return results;
+}
+// ─── Session management ────────────────────────────────────────────────────────
+const SESSION_PATH = '.taproot/.truth-check-session';
+function computeHash(stagedDocs, truths) {
+    const h = createHash('sha256');
+    for (const d of [...stagedDocs].sort((a, b) => a.path.localeCompare(b.path))) {
+        h.update(`doc:${d.path}\x00${d.content}\x00`);
+    }
+    for (const t of [...truths].sort((a, b) => a.relPath.localeCompare(b.relPath))) {
+        h.update(`truth:${t.relPath}\x00${t.content}\x00`);
+    }
+    return h.digest('hex');
+}
+/**
+ * Write a truth-check session marker after the agent has approved the truth check.
+ * Called by `taproot truth-sign`.
+ */
+export function writeTruthSession(cwd, stagedDocs, truths) {
+    const sessionFile = join(cwd, SESSION_PATH);
+    mkdirSync(dirname(sessionFile), { recursive: true });
+    const session = {
+        hash: computeHash(stagedDocs, truths),
+        timestamp: new Date().toISOString(),
+    };
+    writeFileSync(sessionFile, JSON.stringify(session, null, 2) + '\n');
+}
+/**
+ * Validate that a truth-check session exists and matches the current staging state.
+ * Called by the pre-commit hook.
+ */
+export function validateTruthSession(cwd, stagedDocs, truths) {
+    const sessionFile = join(cwd, SESSION_PATH);
+    if (!existsSync(sessionFile)) {
+        return {
+            valid: false,
+            reason: 'no truth-check session found — run /tr-commit to check truths before committing',
+        };
+    }
+    let session;
+    try {
+        session = JSON.parse(readFileSync(sessionFile, 'utf-8'));
+    }
+    catch {
+        return { valid: false, reason: 'truth-check session file is malformed — re-run /tr-commit' };
+    }
+    if (session.hash !== computeHash(stagedDocs, truths)) {
+        return {
+            valid: false,
+            reason: 'staged files or truths have changed since the last truth check — re-run /tr-commit',
+        };
+    }
+    return { valid: true, reason: '' };
+}
+//# sourceMappingURL=truth-checker.js.map

package/dist/core/truth-checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truth-checker.js","sourceRoot":"","sources":["../../src/core/truth-checker.ts"],"names":[],"mappings":"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"}

package/dist/validators/types.d.ts

@@ -68,4 +68,8 @@ export interface TaprootConfig {
     definitionOfDone?: DodConditionEntry[];
     definitionOfReady?: DodConditionEntry[];
     cli?: string;
+    autonomous?: boolean;
+    testsCommand?: string;
+    testResultMaxAge?: number;
+    testTimeout?: number;
 }

package/docs/agents.md

@@ -8,6 +8,7 @@ Taproot works with any AI assistant that can read files. Run `taproot init --age
 |-------|-------------|---------|---------------------|
 | Claude Code | **Tier 1** — fully supported | `taproot init --agent claude` | `.claude/commands/tr-*.md` — one file per slash command |
 | Gemini CLI | **Tier 2** — implemented & tested | `taproot init --agent gemini` | `.gemini/commands/tr-*.toml` — one file per command |
+| Aider | **Tier 2** — implemented & tested | `taproot init --agent aider` | `.aider.conf.yml` with `read:` entries + `CONVENTIONS.md` |
 | Cursor | **Tier 3** — community supported | `taproot init --agent cursor` | `.cursor/rules/taproot.md` — project-wide rules |
 | GitHub Copilot | **Tier 3** — community supported | `taproot init --agent copilot` | `.github/copilot-instructions.md` |
 | Windsurf | **Tier 3** — community supported | `taproot init --agent windsurf` | `.windsurfrules` |
@@ -69,6 +70,16 @@ This refreshes all adapter files and skill definitions to the current version. R
 
 ---
 
+## Aider
+
+The Aider adapter installs `.aider.conf.yml` with `read:` entries so every Aider session automatically loads all taproot skill definitions and `CONVENTIONS.md` as context. No extra flags needed — run `aider` in the project directory and it picks up taproot context immediately.
+
+Skills are invoked by natural language: *"implement the behaviour at taproot/my-intent/my-feature/"* rather than a slash command.
+
+If `.aider.conf.yml` already exists, `taproot init` merges the `read:` entries without removing your existing settings (model, API key, etc.). If the file contains invalid YAML, the command stops with an error rather than overwriting it.
+
+---
+
 ## Non-Claude agents
 
 For Cursor, Copilot, and Windsurf, the adapter installs a rules or instructions file. These give the agent context on the taproot hierarchy, the document formats, and the commit convention — enough to read and navigate the hierarchy, write conformant documents, and use the CLI commands correctly.

package/docs/cli.md

@@ -170,7 +170,7 @@ Surfaces unimplemented behaviours as work items, ordered by priority (intents wi
 ### `taproot dod`
 
 ```bash
-taproot dod [impl-path] [--dry-run]
+taproot dod [impl-path] [--dry-run] [--rerun-tests]
 taproot dod <impl-path> --resolve <condition> --note "<text>" [--resolve <condition> --note "<text>" ...]
 ```
 
@@ -178,6 +178,8 @@ Runs all configured DoD conditions from `.taproot/settings.yaml` against the spe
 
 Use `--resolve`/`--note` to record agent resolutions for agent-driven conditions (e.g. `document-current`, `check-if-affected`, `check-if-affected-by`). Multiple pairs can be supplied in a single invocation — conditions are paired with notes by position.
 
+Use `--rerun-tests` to force re-execution of `testsCommand` regardless of any cached result. Requires `<impl-path>`.
+
 See [Configuration](configuration.md) for how to define DoD conditions.
 
 ---
@@ -196,7 +198,7 @@ The hook uses a three-tier classification, where the implementation tier is dete
 
 | Staged files | Gate applied |
 |---|---|
-| Only hierarchy files (`intent.md`, `usecase.md`) | `validate-structure` + `validate-format` — hierarchy must be valid before the commit lands |
+| Only hierarchy files (`intent.md`, `usecase.md`) | `validate-structure` + `validate-format` + truth consistency check (if `taproot/global-truths/` contains applicable truths) |
 | Only `impl.md` (no source files in map) | Definition of Ready — the parent `usecase.md` must be in `specified` state and have `## Flow` and `## Related` sections |
 | Source files found in map + `impl.md` staged | Verify only `## Status` (and `## DoD Resolutions`) changed in `impl.md`; then run DoD |
 | Source files found in map but `impl.md` NOT staged | **Blocked** — "Stage `impl.md` alongside your source files. No implementation commit should proceed without its traceability record." |
@@ -204,6 +206,20 @@ The hook uses a three-tier classification, where the implementation tier is dete
 
 The DoR gate prevents committing an implementation record before the behaviour is fully specified. The DoD gate prevents marking an implementation complete without passing the quality checks defined in `.taproot/settings.yaml`.
 
+**Truth consistency check:** when hierarchy files are staged and `taproot/global-truths/` exists, the hook validates that a truth-check session marker (`.taproot/.truth-check-session`) is present and matches the current staged content. This marker is written by `taproot truth-sign`, which `/tr-commit` calls after the agent approves the truth check. Committing hierarchy files directly with `git commit` (bypassing `/tr-commit`) will be blocked if applicable truths exist.
+
+---
+
+### `taproot truth-sign`
+
+```bash
+taproot truth-sign
+```
+
+Records a truth-check session marker after the agent has verified that staged hierarchy documents are consistent with applicable truths in `taproot/global-truths/`. Called automatically by the `/tr-commit` skill — you do not need to invoke this directly unless scripting a custom commit workflow.
+
+The session marker is a SHA-256 hash of the staged document contents combined with all applicable truth file contents. If the staged files or truths change after signing, the marker is invalidated and the pre-commit hook will require re-signing.
+
 ---
 
 ## Commit Convention

package/docs/configuration.md

@@ -64,7 +64,7 @@ The `definitionOfDone` list controls what `taproot dod` checks and what the pre-
 
 | Form | What it does |
 |------|-------------|
-| `tests-passing` | Built-in: runs `npm test` (or `yarn test`). Passes if exit code is 0. |
+| `tests-passing` | Built-in: runs `npm test`. When `testsCommand` is configured in `settings.yaml`, uses evidence-backed execution with a cache file — see [State Transition Guardrails](#state-transition-guardrails). |
 | `linter-clean` | Built-in: runs `npm run lint`. Passes if exit code is 0. |
 | `commit-conventions` | Built-in: runs `npm run check:commits`. Passes if exit code is 0. |
 | `document-current: <description>` | Agent-verified: the agent checks whether the described documentation is current and applies updates if needed. |
@@ -106,6 +106,50 @@ Taproot's own `.taproot/settings.yaml` ships with several `check-if-affected-by`
 
 ---
 
+## Autonomous Execution
+
+Setting `autonomous: true` in `settings.yaml` (or `TAPROOT_AUTONOMOUS=1` / `--autonomous` per invocation) puts all agent skills into non-interactive mode.
+
+```yaml
+autonomous: true   # all sessions in this repo run without confirmation prompts
+```
+
+**What autonomous mode changes:**
+- `/tr-implement` proceeds from plan to code without pausing for plan approval
+- `/tr-commit` stages and commits without asking for confirmation when nothing is pre-staged
+- DoD conditions are self-evaluated: resolvable conditions are recorded directly; unresolvable `check:` questions are marked `<!-- autonomous: pending-review -->` in `impl.md`
+- Test failures or hook rejections are recorded in `impl.md` (impl marked `needs-rework`) and the agent stops — the developer returns to a clear failure report
+
+**Three activation mechanisms (in order of scope):**
+1. `autonomous: true` in `.taproot/settings.yaml` — repo-wide, all sessions
+2. `TAPROOT_AUTONOMOUS=1` environment variable — per process invocation
+3. `--autonomous` flag on a skill invocation (e.g. `/tr-implement path/ --autonomous`) — per skill
+
+When none of these is set, confirmation prompts are shown as normal. Autonomous mode is never inferred from context.
+
+---
+
+## State Transition Guardrails
+
+When `testsCommand` is set in `settings.yaml`, the `tests-passing` condition uses evidence-backed execution: it runs the command, caches the result in `.taproot/.test-results/`, and enforces freshness at commit time.
+
+```yaml
+testsCommand: npm test        # command to run for evidence-backed tests-passing
+testResultMaxAge: 60          # minutes before a no-source-file cache is stale (default: 60)
+testTimeout: 300              # seconds before testsCommand is killed (default: 300)
+```
+
+**How it works:**
+- `taproot dod <impl-path>` runs `testsCommand`, streams output live, and writes `.taproot/.test-results/<intent>/<behaviour>/<impl>.json`
+- On subsequent runs, the cached result is used if it is not stale (no tracked source files changed since the last run)
+- `taproot dod <impl-path> --rerun-tests` forces re-execution regardless of cache
+- `--resolve "tests-passing"` is rejected when `testsCommand` is configured — evidence is required, not agent assertion
+- The pre-commit hook verifies a fresh passing result exists before allowing an implementation commit with a `complete` impl
+
+**Add `.taproot/.test-results/` to `.gitignore`** — the cache is a local execution artifact, not a committed record.
+
+---
+
 ## Definition of Ready
 
 The `definitionOfReady` list controls what the pre-commit hook checks when you make a declaration commit (committing `impl.md` without source files). All conditions must pass before the declaration commit is accepted.

package/docs/patterns.md

@@ -116,3 +116,78 @@ The agent reads the question text, reasons whether the answer is yes, no, or not
 |---|---|
 | `does this story introduce a cross-cutting concern that warrants a new check-if-affected-by or check-if-affected entry in .taproot/settings.yaml?` | Agent adds the entry to `.taproot/settings.yaml` |
 | `does this story reveal a reusable pattern worth documenting in docs/patterns.md?` | Agent adds a pattern entry to `docs/patterns.md` |
+
+---
+
+## Autonomous mode preamble (`## Autonomous mode` section in skills)
+
+**Problem:** A skill has one or more confirmation prompts (plan approval, staging confirmation, DoD resolution prompts). You want the same skill to work in both interactive and non-interactive (CI, headless agent) contexts without maintaining two versions.
+
+**Pattern:** Add an `## Autonomous mode` section at the top of the skill file (before `## Steps`) that tells the agent to check for autonomous mode activation and apply autonomous notes throughout the steps.
+
+```markdown
+## Autonomous mode
+
+Before following any steps, check whether autonomous mode is active:
+- `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
+- `--autonomous` was passed as an argument to this skill invocation, **or**
+- `.taproot/settings.yaml` contains `autonomous: true`
+
+If any of these is true, **autonomous mode is active** — apply the autonomous notes at each step where they appear. If none is true, autonomous mode is **inactive** — show confirmation prompts as normal.
+```
+
+Then at each confirmation step, add a conditional note:
+
+```markdown
+**Interactive mode:** ask "Should I proceed?" and wait for confirmation.
+
+**Autonomous mode:** proceed directly without waiting for confirmation.
+```
+
+**When to use it:**
+- The skill has at least one confirmation prompt that would block unattended execution
+- You want CI agents, headless runners, or `TAPROOT_AUTONOMOUS=1` users to be able to run the skill without interaction
+- The skill already exists and works correctly in interactive mode — this is an additive change
+
+**When NOT to use it:**
+- The confirmation prompt exists to prevent destructive irreversible actions (e.g. deleting data, force-pushing) — in these cases, autonomous bypass is unsafe
+- The skill is already fully automated (no prompts) — the preamble adds noise without value
+
+**Taproot's built-in uses:**
+
+| Skill | Prompt bypassed in autonomous mode |
+|---|---|
+| `skills/implement.md` | Plan approval in step 4 |
+| `skills/commit.md` | Staging confirmation in step 3 |
+
+---
+
+## Agent-verified pre-commit check (`taproot truth-sign`)
+
+**Problem:** A pre-commit hook needs to enforce a quality rule that requires semantic reasoning — something a shell command cannot evaluate alone (e.g. "does this spec contradict any active global truths?"). Running an LLM inside a hook is too slow and requires credentials.
+
+**Pattern:** Separate the reasoning from the enforcement:
+1. The skill performs the semantic check (via the agent) before `git commit` is called
+2. If the check passes, the skill runs `taproot truth-sign` to write a session marker (`.taproot/.truth-check-session`) containing a SHA-256 hash of the checked content
+3. The hook validates the marker exists and matches the current staged state — a fast, deterministic check
+
+```bash
+# In the skill (after agent approves):
+taproot truth-sign
+
+# In the hook (synchronous, no LLM needed):
+# validateTruthSession(cwd, stagedDocs, truths)
+```
+
+**When to use it:**
+- The quality rule requires reasoning the CLI cannot perform alone
+- The agent is always in the loop (via a skill) before the commit reaches the hook
+- Content-hash binding is sufficient — the hook does not need to know *why* the check passed, only that it did for this exact content
+
+**Limitation:** If the developer bypasses the skill and runs `git commit` directly, the hook blocks. This is intentional — the pattern enforces use of the skill as the authoritative commit path.
+
+**Taproot's built-in uses:**
+
+| Hook check | Written by | Validates |
+|---|---|---|
+| Truth consistency | `taproot truth-sign` (called by `/tr-commit`) | Staged hierarchy docs are consistent with `taproot/global-truths/` |

package/docs/workflows.md

@@ -136,6 +136,20 @@ Use `/tr-review` on a fresh spec before starting implementation. Use `/tr-review
 
 ---
 
+## Surfacing implicit project truths
+
+After building up several specs, some domain terms and business rules will recur across specs without being formally captured. Use `/tr-discover-truths` to surface them:
+
+```
+/tr-discover-truths
+```
+
+The skill scans all `intent.md` and `usecase.md` files, identifies recurring terms, business rules, and conventions not yet defined in `taproot/global-truths/`, and presents them as candidates. For each candidate you choose: **promote** (routes to `/tr-ineed` → define-truth), **backlog** (saves to `.taproot/backlog.md` for later), **skip** (reappears next run), or **dismiss** (permanently suppressed).
+
+Truth discovery also runs as a final pass inside `/tr-review-all`, appending a `## Truth Candidates` section to the review report.
+
+---
+
 ## When you need to think something through
 
 ```