truthtrail 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhairya Modh
+
+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

@@ -74,3 +74,13 @@ The plugin (in `plugin/` of the TruthTrail repo) adds:
 | `decisionsDir` | `.decisions` | where records live |
 | `jiraSite` | `null` | used by the TruthTrail server |
 | `failOnUnconfirmed` | `false` | used by the TruthTrail server's PR check |
+
+## Troubleshooting: help improve answer capture
+
+The Claude Code hook that captures your answers to "A or B?" questions is built from documentation that doesn't describe the exact payload. If answered questions never show up in `npx truthtrail pending list`, run Claude Code with:
+
+```bash
+TRUTHTRAIL_DEBUG_HOOKS=1 claude
+```
+
+Answer one question, then open `.truthtrail/hook-payloads.jsonl` and share it in an issue (remove anything private first). It is git-ignored and stays on your machine.

package/dist/index.js

@@ -48,7 +48,7 @@ function validateRecord(obj) {
 }
 var FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 function parseRecord(text) {
-  const m = FRONT_MATTER.exec(text);
+  const m = FRONT_MATTER.exec(text.replace(/^\uFEFF/, ""));
   if (!m) throw new RecordError(["missing --- front matter"]);
   let data;
   try {
@@ -226,7 +226,7 @@ async function walk(dir) {
   for (const e of entries) {
     const p = join2(dir, e.name);
     if (e.isDirectory()) out.push(...await walk(p));
-    else if (e.name.endsWith(".md")) out.push(p);
+    else if (e.name.endsWith(".md") && e.name.toLowerCase() !== "readme.md") out.push(p);
   }
   return out;
 }
@@ -238,7 +238,7 @@ async function listRecords(root, cfg, ticket) {
     const rel = abs.slice(root.length + 1).split("\\").join("/");
     try {
       const r = parseRecord(await readFile2(abs, "utf8"));
-      if (!ticket || r.ticket === ticket) records.push({ ...r, path: rel });
+      if (!ticket || r.ticket.toUpperCase() === ticket.toUpperCase()) records.push({ ...r, path: rel });
     } catch (e) {
       errors.push({ path: rel, message: e instanceof RecordError ? e.problems.join("; ") : e.message });
     }
@@ -495,7 +495,10 @@ async function sessionStartContext(root, cfg, branch) {
     return "TruthTrail: no ticket key in this branch name. Before recording decisions, ask the user for the ticket key once.";
   }
   const { records } = await listRecords(root, cfg, ticket);
-  const lines = [`TruthTrail: working on ticket ${ticket}. Follow the TruthTrail rules in AGENTS.md.`];
+  const lines = [
+    `TruthTrail: working on ticket ${ticket}. Follow the TruthTrail rules in AGENTS.md.`,
+    "If TruthTrail MCP tools are available, use record_decision to save decisions and list_pending / resolve_pending for answered questions; otherwise use the npx truthtrail commands."
+  ];
   if (records.length === 0) lines.push("No decisions recorded for this ticket yet.");
   else {
     lines.push(`Recorded decisions for ${ticket} (follow them):`);
@@ -520,10 +523,10 @@ Record each one that changes behaviour a user or QA can see; dismiss the rest. I
 import { realpath } from "fs/promises";
 var clean = (xs) => (xs ?? []).map((x) => x.trim()).filter(Boolean);
 async function recordDecision(root, cwd, cfg, input, now) {
-  if (!input.question?.trim()) throw new Error("--question is required");
-  if (!input.chosen?.trim()) throw new Error("--chosen is required");
+  if (!input.question?.trim()) throw new Error("question is required");
+  if (!input.chosen?.trim()) throw new Error("chosen is required");
   const type = input.type ?? "decision";
-  if (!DECISION_TYPES.includes(type)) throw new Error(`--type must be one of ${DECISION_TYPES.join(", ")}`);
+  if (!DECISION_TYPES.includes(type)) throw new Error(`type must be one of ${DECISION_TYPES.join(", ")}`);
   let ticket = input.ticket?.trim().toUpperCase() || null;
   if (ticket && !new RegExp(`^(?:${cfg.ticketPattern})$`, "i").test(ticket)) {
     throw new Error(`'${input.ticket}' is not a valid ticket key (expected pattern ${cfg.ticketPattern})`);
@@ -531,12 +534,12 @@ async function recordDecision(root, cwd, cfg, input, now) {
   if (!ticket) {
     const branch = await currentBranch(root);
     ticket = detectTicket({ branch }, cfg.ticketPattern);
-    if (!ticket) throw new Error(`No ticket key found in branch '${branch ?? "(detached)"}'. Pass --ticket <KEY>.`);
+    if (!ticket) throw new Error(`No ticket key found in branch '${branch ?? "(detached)"}'. Pass a ticket key (ticket, or --ticket <KEY> on the CLI).`);
   }
   const base = await realpath(cwd).catch(() => cwd);
   const files = clean(input.files).map((f) => {
     const rel = toRepoPath(root, base, f);
-    if (!rel) throw new Error(`--files: ${f} is outside the repository`);
+    if (!rel) throw new Error(`files: ${f} is outside the repository`);
     return rel;
   });
   return writeRecord(
@@ -562,7 +565,7 @@ async function recordDecision(root, cwd, cfg, input, now) {
 }
 async function resolvePending(root, cwd, cfg, index, overrides, now) {
   const entry = (await listPending(root)).find((p) => p.index === index);
-  if (!entry) throw new Error(`No pending question #${index}. Run \`npx truthtrail pending list\`.`);
+  if (!entry) throw new Error(`No pending question #${index}. List them with list_pending or \`npx truthtrail pending list\`.`);
   const given = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== void 0));
   const record = await recordDecision(
     root,
@@ -587,7 +590,9 @@ var MCP_TARGETS = [
   { file: ".vscode/mcp.json", key: "servers", entry: { type: "stdio", command: "npx", args: ARGS } }
 ];
 var FORMAT = {};
-function upsertMcpEntry(existing, target) {
+function upsertMcpEntry(raw, target) {
+  const bom = raw?.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const existing = raw === null ? null : raw.slice(bom.length);
   if (existing === null || existing.trim() === "") {
     return { status: "created", text: `${JSON.stringify({ [target.key]: { truthtrail: target.entry } }, null, 2)}
 ` };
@@ -598,10 +603,10 @@ function upsertMcpEntry(existing, target) {
   if (tree.type !== "object") return { status: "skipped", reason: "top level is not a JSON object" };
   const parent = findNodeAtLocation(tree, [target.key]);
   if (parent && parent.type !== "object") return { status: "skipped", reason: `"${target.key}" is not an object` };
-  if (findNodeAtLocation(tree, [target.key, "truthtrail"])) return { status: "unchanged", text: existing };
+  if (findNodeAtLocation(tree, [target.key, "truthtrail"])) return { status: "unchanged", text: raw };
   try {
     const text = applyEdits(existing, modify(existing, [target.key, "truthtrail"], target.entry, FORMAT));
-    return { status: "added", text };
+    return { status: "added", text: bom + text };
   } catch (e) {
     return { status: "skipped", reason: e.message };
   }
@@ -815,6 +820,8 @@ async function runPendingDismiss(cwd, index) {
 }
 
 // src/commands/hook.ts
+import { appendFile as appendFile2, mkdir as mkdir4 } from "fs/promises";
+import { join as join6 } from "path";
 async function runHook(event, stdin, cwd) {
   try {
     let payload = null;
@@ -829,6 +836,11 @@ async function runHook(event, stdin, cwd) {
       return await sessionStartContext(root, await loadConfig(root), await currentBranch(root));
     }
     if (event === "capture") {
+      if (process.env.TRUTHTRAIL_DEBUG_HOOKS === "1") {
+        await mkdir4(join6(root, ".truthtrail"), { recursive: true });
+        await appendFile2(join6(root, ".truthtrail", "hook-payloads.jsonl"), `${JSON.stringify(payload)}
+`);
+      }
       for (const a of extractAskAnswers(payload)) {
         await appendPending(root, { ...a, at: (/* @__PURE__ */ new Date()).toISOString() });
       }
@@ -884,7 +896,7 @@ var decisionFields = {
 };
 function createServer(opts) {
   const now = opts.now ?? (() => /* @__PURE__ */ new Date());
-  const server = new McpServer({ name: "truthtrail", version: "0.2.0" });
+  const server = new McpServer({ name: "truthtrail", version: "0.2.1" });
   async function workspace() {
     const candidates = [];
     if (server.server.getClientCapabilities()?.roots) {
@@ -989,7 +1001,7 @@ async function runMcp() {
 // src/index.ts
 function buildProgram() {
   const program = new Command();
-  program.name("truthtrail").description("Record the decisions your AI coding agent makes, right next to the code.").version("0.2.0");
+  program.name("truthtrail").description("Record the decisions your AI coding agent makes, right next to the code.").version("0.2.1");
   program.command("init").description("Set up TruthTrail in this repo (.decisions/, AGENTS.md rules, MCP config, config)").option("--no-mcp", "don't write MCP config for Claude Code, Cursor and Copilot").action(async (o) => {
     await runInit(process.cwd(), (l) => console.log(l), { mcp: o.mcp });
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truthtrail",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Record the decisions your AI coding agent makes, right next to the code.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=20"