truthtrail 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# TruthTrail
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+When your AI coding agent hits something the ticket doesn't settle ("empty date: show an error or use today?"), the decision usually disappears into a chat or a call. Then QA's AI files a false defect against the stale ticket. TruthTrail records those decisions **next to the code**, in `.decisions/`, so every role and every AI reads the same truth.
+
+This package is the local CLI. Syncing decisions into Jira, confirmation by the ticket reporter, and PR checks come with the TruthTrail server (coming next).
+
+## Install
+
+```bash
+npx truthtrail init
+```
+
+`init` adds:
+- `.decisions/`, where decision records live (commit them)
+- a short rules block in `AGENTS.md`, read by Claude Code, Copilot, Cursor, Codex and others. Your own text is never touched.
+- a pointer in `CLAUDE.md`, if you have one
+- `.truthtrail.json` (config) and `.truthtrail/` in `.gitignore`
+
+It prints exactly what it changed. Running it again is safe.
+
+## Commands
+
+```bash
+# Record a decision for the ticket in your branch name (feature/JIRA-231-…)
+npx truthtrail decide --question "Discount before or after tax?" \
+  --chosen "Before tax" --options "Before tax|After tax" \
+  --reason "Finance rule" --files billing/total.ts
+
+# Record an assumption your AI made without asking
+npx truthtrail decide --type assumption --question "Empty discount?" --chosen "Treat as 0"
+
+# See decisions for a ticket
+npx truthtrail list --ticket JIRA-231
+
+# Who wrote this line, AI or human, and which decisions shaped it?
+npx truthtrail why billing/total.ts:42
+
+# Check this branch: ticket found? AI commits without any decision recorded?
+npx truthtrail check --base main
+```
+
+`--approver <name>` is only for when someone explicitly approved. TruthTrail never guesses approvers.
+
+## Claude Code plugin
+
+The plugin (in `plugin/` of the TruthTrail repo) adds:
+- **SessionStart:** loads the ticket's decisions into Claude's context
+- **Capture:** remembers questions you answered through Claude's "A or B?" prompts
+- **Stop:** before Claude finishes, asks it to record each answered question that changes visible behaviour (`decide --from-pending <n>`) or dismiss it (`pending dismiss <n>`)
+
+## Config (`.truthtrail.json`)
+
+| Key | Default | Meaning |
+|---|---|---|
+| `ticketPattern` | `[A-Z][A-Z0-9]+-\d+` | how ticket keys look (matched case-insensitively) |
+| `decisionsDir` | `.decisions` | where records live |
+| `jiraSite` | `null` | used by the TruthTrail server |
+| `failOnUnconfirmed` | `false` | used by the TruthTrail server's PR check |

package/dist/index.js

@@ -0,0 +1,808 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import { access, appendFile, mkdir as mkdir3, readFile as readFile5, realpath, writeFile as writeFile3 } from "fs/promises";
+import { join as join5 } from "path";
+
+// ../core/src/types.ts
+var DECISION_TYPES = ["decision", "assumption", "impact"];
+var AGENT_NAMES = ["claude-code", "copilot", "cursor", "codex", "aider", "other", "none"];
+var RECORD_SOURCES = ["ai-session", "manual"];
+
+// ../core/src/record.ts
+import { parse, stringify } from "yaml";
+var RecordError = class extends Error {
+  constructor(problems) {
+    super(`Invalid decision record: ${problems.join("; ")}`);
+    this.problems = problems;
+    this.name = "RecordError";
+  }
+  problems;
+};
+var REQUIRED_STRINGS = ["id", "ticket", "question", "chosen", "decided_by", "created_at"];
+var ARRAY_FIELDS = ["options", "files", "supersedes"];
+function validateRecord(obj) {
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) return ["record must be an object"];
+  const o = obj;
+  const problems = [];
+  for (const f of REQUIRED_STRINGS) {
+    if (typeof o[f] !== "string" || o[f].trim() === "") problems.push(`${f} is required`);
+  }
+  if (o.reason !== void 0 && typeof o.reason !== "string") problems.push("reason must be a string");
+  if (!DECISION_TYPES.includes(o.type)) problems.push(`type must be one of ${DECISION_TYPES.join(", ")}`);
+  if (!AGENT_NAMES.includes(o.agent)) problems.push(`agent must be one of ${AGENT_NAMES.join(", ")}`);
+  if (!RECORD_SOURCES.includes(o.source)) problems.push(`source must be one of ${RECORD_SOURCES.join(", ")}`);
+  if (o.approver_claimed !== void 0 && o.approver_claimed !== null && typeof o.approver_claimed !== "string") {
+    problems.push("approver_claimed must be a string or null");
+  }
+  for (const f of ARRAY_FIELDS) {
+    const v = o[f];
+    if (v !== void 0 && !(Array.isArray(v) && v.every((x) => typeof x === "string"))) {
+      problems.push(`${f} must be a list of strings`);
+    }
+  }
+  return problems;
+}
+var FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+function parseRecord(text) {
+  const m = FRONT_MATTER.exec(text);
+  if (!m) throw new RecordError(["missing --- front matter"]);
+  let data;
+  try {
+    data = parse(m[1]);
+  } catch (e) {
+    throw new RecordError([`invalid YAML: ${e.message.split("\n")[0]}`]);
+  }
+  const problems = validateRecord(data);
+  if (problems.length) throw new RecordError(problems);
+  const o = data;
+  return {
+    id: o.id,
+    ticket: o.ticket,
+    type: o.type,
+    question: o.question,
+    options: o.options ?? [],
+    chosen: o.chosen,
+    reason: o.reason ?? "",
+    decided_by: o.decided_by,
+    approver_claimed: o.approver_claimed ?? null,
+    agent: o.agent,
+    source: o.source,
+    files: o.files ?? [],
+    created_at: String(o.created_at),
+    supersedes: o.supersedes ?? [],
+    body: m[2].trim()
+  };
+}
+function serializeRecord(r) {
+  const { body, ...front } = r;
+  const yaml = stringify(front, { lineWidth: 0 }).trimEnd();
+  return `---
+${yaml}
+---
+${body.trim()}
+`;
+}
+
+// ../core/src/ids.ts
+import { createHash } from "crypto";
+function slugify(text, maxLen = 40) {
+  const s = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, maxLen).replace(/-+$/g, "");
+  return s || "decision";
+}
+function stamp(d) {
+  return d.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+}
+function makeId(stem) {
+  return `D-${stem}`;
+}
+function recordRelPath(decisionsDir, ticket, stem) {
+  return `${decisionsDir.replace(/\/+$/, "")}/${ticket}/${stem}.md`;
+}
+
+// ../core/src/config.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+var DEFAULT_CONFIG = {
+  ticketPattern: "[A-Z][A-Z0-9]+-\\d+",
+  jiraSite: null,
+  failOnUnconfirmed: false,
+  decisionsDir: ".decisions"
+};
+var CONFIG_FILE = ".truthtrail.json";
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+async function loadConfig(repoRoot2) {
+  const path = join(repoRoot2, CONFIG_FILE);
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return { ...DEFAULT_CONFIG };
+    throw e;
+  }
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (e) {
+    throw new ConfigError(`${CONFIG_FILE} is not valid JSON: ${e.message}`);
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new ConfigError(`${CONFIG_FILE} must contain a JSON object`);
+  }
+  return { ...DEFAULT_CONFIG, ...data };
+}
+
+// ../core/src/ticket.ts
+function detectTicket(input, pattern = DEFAULT_CONFIG.ticketPattern) {
+  const re = new RegExp(pattern, "i");
+  for (const source of [input.branch, input.prTitle]) {
+    if (!source) continue;
+    const m = re.exec(source);
+    if (m) return m[0].toUpperCase();
+  }
+  return null;
+}
+
+// ../core/src/git.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var exec = promisify(execFile);
+var GitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GitError";
+  }
+};
+async function git(cwd, args) {
+  try {
+    const { stdout } = await exec("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+  } catch (e) {
+    const err = e;
+    throw new GitError((err.stderr || err.message).trim());
+  }
+}
+async function repoRoot(cwd) {
+  return (await git(cwd, ["rev-parse", "--show-toplevel"])).trim();
+}
+async function currentBranch(cwd) {
+  const b = (await git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+  return b === "HEAD" ? null : b;
+}
+async function userName(cwd) {
+  try {
+    return (await git(cwd, ["config", "user.name"])).trim() || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function isTracked(cwd, file) {
+  try {
+    await git(cwd, ["ls-files", "--error-unmatch", "--", file]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function blameLine(cwd, file, line) {
+  const out = await git(cwd, ["blame", "--porcelain", "-L", `${line},${line}`, "--", file]);
+  return out.split(" ")[0];
+}
+async function lastCommitForFile(cwd, file) {
+  const sha = (await git(cwd, ["log", "-1", "--format=%H", "--", file])).trim();
+  return sha || null;
+}
+var SEP = "";
+async function commitInfo(cwd, sha) {
+  const out = await git(cwd, ["show", "-s", `--format=%H${SEP}%an${SEP}%ae${SEP}%aI${SEP}%B`, sha]);
+  const [full, authorName, authorEmail, date, ...rest] = out.split(SEP);
+  return { sha: full, authorName, authorEmail, date, message: rest.join(SEP).trim() };
+}
+async function branchCommits(cwd, base) {
+  const out = await git(cwd, ["rev-list", `${base}..HEAD`]);
+  return out.split("\n").filter(Boolean);
+}
+
+// ../core/src/store.ts
+import { mkdir, readdir, readFile as readFile2, writeFile } from "fs/promises";
+import { dirname, join as join2 } from "path";
+async function walk(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  }
+  const out = [];
+  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);
+  }
+  return out;
+}
+async function listRecords(root, cfg, ticket) {
+  const files = await walk(join2(root, cfg.decisionsDir));
+  const records = [];
+  const errors = [];
+  for (const abs of files) {
+    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 });
+    } catch (e) {
+      errors.push({ path: rel, message: e instanceof RecordError ? e.problems.join("; ") : e.message });
+    }
+  }
+  records.sort((a, b) => b.created_at.localeCompare(a.created_at) || b.id.localeCompare(a.id));
+  return { records, errors };
+}
+async function writeRecord(root, cfg, draft, now) {
+  const baseStem = `${stamp(now)}-${slugify(draft.question)}`;
+  for (let n = 1; n < 1e3; n++) {
+    const stem = n === 1 ? baseStem : `${baseStem}-${n}`;
+    const rel = recordRelPath(cfg.decisionsDir, draft.ticket, stem);
+    const record = { ...draft, id: makeId(stem), created_at: now.toISOString() };
+    await mkdir(dirname(join2(root, rel)), { recursive: true });
+    try {
+      await writeFile(join2(root, rel), serializeRecord(record), { flag: "wx" });
+      return { ...record, path: rel };
+    } catch (e) {
+      if (e.code !== "EEXIST") throw e;
+    }
+  }
+  throw new Error(`could not find a free file name for ${baseStem}`);
+}
+
+// ../core/src/authorship.ts
+var TRAILER_AGENTS = [
+  [/claude|anthropic/i, "claude-code"],
+  [/cursor/i, "cursor"],
+  [/copilot/i, "copilot"],
+  [/codex|openai/i, "codex"],
+  [/aider/i, "aider"]
+];
+var HUMAN = { ai: false, agent: null, confidence: null };
+function classifyCommit(message) {
+  const trailers = message.split("\n").filter((l) => /^\s*co-authored-by:/i.test(l));
+  for (const line of trailers) {
+    for (const [re, agent] of TRAILER_AGENTS) {
+      if (re.test(line)) return { ai: true, agent, confidence: "high" };
+    }
+  }
+  if (/Generated with \[?Claude Code/i.test(message)) return { ai: true, agent: "claude-code", confidence: "medium" };
+  if (/^aider:/i.test(message.trimStart())) return { ai: true, agent: "aider", confidence: "medium" };
+  return HUMAN;
+}
+
+// ../core/src/rules.ts
+var BLOCK_START = "<!-- truthtrail:start -->";
+var BLOCK_END = "<!-- truthtrail:end -->";
+var RULES_TEXT = `## TruthTrail: recording decisions
+
+This repo records product decisions in \`.decisions/\`. Follow these rules.
+
+**Find the ticket.** Take the ticket key from the branch name (e.g. \`feature/JIRA-231-\u2026\`). If there is none, ask the user once.
+
+**Before you implement,** run \`npx truthtrail list --ticket <KEY>\` and follow the decisions it shows. Treat \`rejected\` ones as must-rework.
+
+**Record a decision** with \`npx truthtrail decide\` when:
+- the ticket is silent or ambiguous and your choice changes behaviour a user or QA can see;
+- following the ticket would break something, so you changed the behaviour;
+- you assumed something that changes visible behaviour (use \`--type assumption\`).
+
+Do not record pure implementation details with no visible effect.
+
+**Approver:** pass \`--approver <name>\` only if the user explicitly says who approved it. Never guess a name.
+
+**Superseding:** if your decision replaces an older one, pass \`--supersedes <id>\`.
+
+**When testing (QA):** before filing a defect, read the ticket and \`npx truthtrail list --ticket <KEY>\`. Behaviour that matches a decision is not a defect. If that decision is unconfirmed, report "needs confirmation" instead.`;
+var CLAUDE_POINTER = "See the TruthTrail rules in AGENTS.md (decisions are recorded in .decisions/).";
+function upsertBlock(existing, inner) {
+  const block = `${BLOCK_START}
+${inner}
+${BLOCK_END}`;
+  const current = existing ?? "";
+  const starts = current.split(BLOCK_START).length - 1;
+  const ends = current.split(BLOCK_END).length - 1;
+  if (starts !== ends || starts > 1) {
+    throw new Error("unmatched TruthTrail marker: fix the <!-- truthtrail:start/end --> lines by hand, then run init again");
+  }
+  const start = current.indexOf(BLOCK_START);
+  const end = start === -1 ? -1 : current.indexOf(BLOCK_END, start);
+  let text;
+  if (start !== -1 && end !== -1) {
+    text = current.slice(0, start) + block + current.slice(end + BLOCK_END.length);
+  } else if (current === "") {
+    text = `${block}
+`;
+  } else {
+    text = `${current}${current.endsWith("\n") ? "" : "\n"}
+${block}
+`;
+  }
+  return { text, changed: text !== current };
+}
+
+// ../core/src/why.ts
+import { readFile as readFile3 } from "fs/promises";
+import { join as join3 } from "path";
+
+// ../core/src/paths.ts
+import { isAbsolute, relative, resolve } from "path";
+function toRepoPath(root, cwd, file) {
+  const rel = relative(root, isAbsolute(file) ? file : resolve(cwd, file)).split("\\").join("/");
+  if (rel === "" || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) return null;
+  return rel;
+}
+
+// ../core/src/why.ts
+var WhyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WhyError";
+  }
+};
+function parseTarget(arg) {
+  const m = /^(.*):(\d+)$/.exec(arg);
+  return m ? { file: m[1], line: Number(m[2]) } : { file: arg };
+}
+async function whyLocal(root, cfg, target, cwd = root) {
+  const file = toRepoPath(root, cwd, target.file);
+  if (!file) throw new WhyError(`${target.file} is outside the repository`);
+  if (!await isTracked(root, file)) throw new WhyError(`not tracked by git: ${file}`);
+  let sha;
+  if (target.line !== void 0) {
+    const text = await readFile3(join3(root, file), "utf8");
+    const lineCount = text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    if (target.line < 1 || target.line > lineCount) {
+      throw new WhyError(`line ${target.line} is beyond end of ${file} (${lineCount} lines)`);
+    }
+    sha = await blameLine(root, file, target.line);
+  } else {
+    sha = await lastCommitForFile(root, file);
+  }
+  if (!sha || /^0+$/.test(sha)) throw new WhyError(`${file}:${target.line ?? ""} has uncommitted changes; commit first`);
+  const info = await commitInfo(root, sha);
+  const { records } = await listRecords(root, cfg);
+  const decisions = records.filter((r) => r.files.includes(file));
+  const ticket = detectTicket({ prTitle: info.message }, cfg.ticketPattern) ?? decisions[0]?.ticket ?? null;
+  return {
+    file,
+    line: target.line ?? null,
+    commit: { ...info, authorship: classifyCommit(info.message) },
+    ticket,
+    decisions,
+    status: ticket ? `status: see ticket ${ticket}` : "status: no ticket linked"
+  };
+}
+
+// ../core/src/check.ts
+async function checkRepo(root, cfg, base) {
+  const ticket = detectTicket({ branch: await currentBranch(root) }, cfg.ticketPattern);
+  const { records, errors } = await listRecords(root, cfg, ticket ?? void 0);
+  const decisions = ticket ? records : [];
+  const shas = await branchCommits(root, base);
+  let aiCommits = 0;
+  for (const sha of shas) {
+    if (classifyCommit((await commitInfo(root, sha)).message).ai) aiCommits++;
+  }
+  const reminders = [];
+  if (!ticket) reminders.push("No ticket key found in branch name.");
+  else if (aiCommits > 0 && decisions.length === 0) {
+    reminders.push(
+      `This branch has ${aiCommits} AI-assisted commits but no decision records for ${ticket}. If behaviour changed, record it with \`npx truthtrail decide\`.`
+    );
+  }
+  return {
+    ticket,
+    invalid: errors,
+    decisions,
+    assumptions: decisions.filter((d) => d.type === "assumption"),
+    aiCommits,
+    totalCommits: shas.length,
+    reminders
+  };
+}
+
+// ../core/src/pending.ts
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
+import { join as join4 } from "path";
+var pendingPath = (root) => join4(root, ".truthtrail", "pending.jsonl");
+async function listPending(root) {
+  let text;
+  try {
+    text = await readFile4(pendingPath(root), "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  }
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+async function save(root, entries) {
+  await mkdir2(join4(root, ".truthtrail"), { recursive: true });
+  await writeFile2(pendingPath(root), entries.map((e) => JSON.stringify(e)).join("\n") + (entries.length ? "\n" : ""));
+}
+async function appendPending(root, e) {
+  const entries = await listPending(root);
+  const entry = { index: entries.reduce((m, x) => Math.max(m, x.index + 1), 0), ...e };
+  await save(root, [...entries, entry]);
+  return entry;
+}
+async function removePending(root, index) {
+  const entries = await listPending(root);
+  const hit = entries.find((e) => e.index === index) ?? null;
+  if (hit) await save(root, entries.filter((e) => e.index !== index));
+  return hit;
+}
+
+// ../core/src/hooks.ts
+var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function answersFrom(payload, questionTexts) {
+  const resp = payload.tool_response;
+  const input = payload.tool_input;
+  if (isObj(resp) && isObj(resp.answers)) return resp.answers;
+  if (isObj(input.answers)) return input.answers;
+  if (isObj(resp) && questionTexts.some((q) => typeof resp[q] === "string")) return resp;
+  if (typeof resp === "string") {
+    const found = {};
+    for (const m of resp.matchAll(/"([^"]+)"="([^"]*)"/g)) found[m[1]] = m[2];
+    return Object.keys(found).length ? found : null;
+  }
+  return null;
+}
+function extractAskAnswers(payload) {
+  try {
+    if (!isObj(payload) || !isObj(payload.tool_input) || !Array.isArray(payload.tool_input.questions)) return [];
+    const qs = payload.tool_input.questions.filter(isObj).filter((q) => typeof q.question === "string");
+    const answers = answersFrom(payload, qs.map((q) => q.question));
+    if (!answers) return [];
+    const out = [];
+    for (const q of qs) {
+      const answer = answers[q.question];
+      if (typeof answer !== "string" || !answer) continue;
+      const options = Array.isArray(q.options) ? q.options.filter(isObj).map((o) => o.label).filter((l) => typeof l === "string") : [];
+      out.push({ question: q.question, options, answer });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+async function sessionStartContext(root, cfg, branch) {
+  const ticket = detectTicket({ branch }, cfg.ticketPattern);
+  if (!ticket) {
+    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.`];
+  if (records.length === 0) lines.push("No decisions recorded for this ticket yet.");
+  else {
+    lines.push(`Recorded decisions for ${ticket} (follow them):`);
+    for (const r of records) lines.push(`- ${r.id} [${r.type}] ${r.question} \u2192 ${r.chosen}`);
+  }
+  return lines.join("\n");
+}
+async function stopDecision(root, payload) {
+  if (isObj(payload) && payload.stop_hook_active === true) return null;
+  const pending = await listPending(root);
+  if (pending.length === 0) return null;
+  const items = pending.map((p) => `  #${p.index}: ${p.question} \u2192 ${p.answer}`).join("\n");
+  return {
+    decision: "block",
+    reason: `TruthTrail: ${pending.length} answered questions are not classified yet:
+${items}
+For each one that changes behaviour a user or QA can see, run \`npx truthtrail decide --from-pending <n> --reason "\u2026"\`. Otherwise run \`npx truthtrail pending dismiss <n>\`.`
+  };
+}
+
+// src/commands/init.ts
+async function readOrNull(path) {
+  try {
+    return await readFile5(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+var exists = (p) => access(p).then(() => true, () => false);
+var real = (p) => realpath(p).catch(() => p);
+function upsertIn(file, existing, inner) {
+  try {
+    return upsertBlock(existing, inner);
+  } catch (e) {
+    throw new Error(`${file}: ${e.message}`);
+  }
+}
+async function runInit(cwd, log) {
+  const root = await repoRoot(cwd);
+  const changes = [];
+  const note = (file, what) => {
+    changes.push(file);
+    log(`${what.padEnd(8)}${file}`);
+  };
+  const agentsPath = join5(root, "AGENTS.md");
+  const agents = await readOrNull(agentsPath);
+  const a = upsertIn("AGENTS.md", agents, RULES_TEXT);
+  const claudePath = join5(root, "CLAUDE.md");
+  const claude = await readOrNull(claudePath);
+  const claudeIsAgents = claude !== null && await real(claudePath) === await real(agentsPath);
+  const c = claude !== null && !claudeIsAgents ? upsertIn("CLAUDE.md", claude, CLAUDE_POINTER) : null;
+  const keep = join5(root, DEFAULT_CONFIG.decisionsDir, ".gitkeep");
+  if (!await exists(keep)) {
+    await mkdir3(join5(root, DEFAULT_CONFIG.decisionsDir), { recursive: true });
+    await writeFile3(keep, "");
+    note(".decisions/.gitkeep", "added");
+  }
+  if (a.changed) {
+    await writeFile3(agentsPath, a.text);
+    note("AGENTS.md", agents === null ? "added" : "updated");
+  }
+  if (c?.changed) {
+    await writeFile3(claudePath, c.text);
+    note("CLAUDE.md", "updated");
+  }
+  const configPath = join5(root, CONFIG_FILE);
+  if (!await exists(configPath)) {
+    await writeFile3(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
+`);
+    note(CONFIG_FILE, "added");
+  }
+  const ignorePath = join5(root, ".gitignore");
+  const ignore = await readOrNull(ignorePath);
+  if (!ignore?.split("\n").some((l) => l.trim() === ".truthtrail/")) {
+    const prefix = ignore && !ignore.endsWith("\n") ? "\n" : "";
+    await appendFile(ignorePath, `${prefix}.truthtrail/
+`);
+    note(".gitignore", ignore === null ? "added" : "updated");
+  }
+  if (changes.length === 0) log("TruthTrail: no changes");
+  return { changes };
+}
+
+// src/commands/decide.ts
+import { realpath as realpath2 } from "fs/promises";
+var list = (s, sep) => (s ?? "").split(sep).map((x) => x.trim()).filter(Boolean);
+async function repoFiles(root, cwd, files) {
+  const base = await realpath2(cwd);
+  return files.map((f) => {
+    const rel = toRepoPath(root, base, f);
+    if (!rel) throw new Error(`--files: ${f} is outside the repository`);
+    return rel;
+  });
+}
+function detectAgent(o, env) {
+  if (o.agent) {
+    if (!AGENT_NAMES.includes(o.agent)) throw new Error(`--agent must be one of ${AGENT_NAMES.join(", ")}`);
+    return o.agent;
+  }
+  return env.CLAUDECODE === "1" ? "claude-code" : "none";
+}
+async function runDecide(cwd, input, env, now) {
+  let o = input;
+  if (input.fromPending !== void 0) {
+    const entry = (await listPending(await repoRoot(cwd))).find((p) => p.index === Number(input.fromPending));
+    if (!entry) throw new Error(`No pending question #${input.fromPending}. Run \`npx truthtrail pending list\`.`);
+    const given = Object.fromEntries(Object.entries(input).filter(([, v]) => v !== void 0));
+    o = { question: entry.question, chosen: entry.answer, options: entry.options.join("|"), ...given };
+  }
+  const record = await decide(cwd, o, env, now);
+  if (input.fromPending !== void 0) await removePending(await repoRoot(cwd), Number(input.fromPending));
+  return record;
+}
+async function decide(cwd, o, env, now) {
+  if (!o.question?.trim()) throw new Error("--question is required");
+  if (!o.chosen?.trim()) throw new Error("--chosen is required");
+  const type = o.type ?? "decision";
+  if (!DECISION_TYPES.includes(type)) throw new Error(`--type must be one of ${DECISION_TYPES.join(", ")}`);
+  const root = await repoRoot(cwd);
+  const cfg = await loadConfig(root);
+  let ticket = o.ticket?.trim().toUpperCase() || null;
+  if (ticket && !new RegExp(`^(?:${cfg.ticketPattern})$`, "i").test(ticket)) {
+    throw new Error(`'${o.ticket}' is not a valid ticket key (expected pattern ${cfg.ticketPattern})`);
+  }
+  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>.`);
+  }
+  const agent = detectAgent(o, env);
+  return writeRecord(
+    root,
+    cfg,
+    {
+      ticket,
+      type,
+      question: o.question.trim(),
+      options: list(o.options, "|"),
+      chosen: o.chosen.trim(),
+      reason: o.reason?.trim() ?? "",
+      decided_by: await userName(root),
+      approver_claimed: o.approver?.trim() || null,
+      agent,
+      source: agent === "none" ? "manual" : "ai-session",
+      files: await repoFiles(root, cwd, list(o.files, ",")),
+      supersedes: list(o.supersedes, ","),
+      body: o.body?.trim() ?? ""
+    },
+    now
+  );
+}
+
+// src/commands/list.ts
+function formatRecord(r) {
+  const lines = [`${r.id}  [${r.type}]  ${r.ticket}`, `  ${r.question}`, `  \u2192 ${r.chosen}`];
+  if (r.reason) lines.push(`  why: ${r.reason}`);
+  lines.push(`  by ${r.decided_by}${r.approver_claimed ? `, approver (claimed): ${r.approver_claimed}` : ""}`);
+  if (r.supersedes.length) lines.push(`  supersedes: ${r.supersedes.join(", ")}`);
+  return lines.join("\n");
+}
+async function runList(cwd, o) {
+  const root = await repoRoot(cwd);
+  const cfg = await loadConfig(root);
+  const ticket = o.ticket?.trim().toUpperCase() || void 0;
+  const { records, errors } = await listRecords(root, cfg, ticket);
+  if (o.json) return JSON.stringify(records, null, 2);
+  const out = errors.map((e) => `! ${e.path}: ${e.message}`);
+  if (records.length === 0) out.push(ticket ? `No decisions recorded for ${ticket}.` : "No decisions recorded.");
+  else out.push(...records.map(formatRecord));
+  return out.join("\n\n");
+}
+
+// src/commands/why.ts
+import { realpath as realpath3 } from "fs/promises";
+function formatWhy(r) {
+  const a = r.commit.authorship;
+  const who = a.ai ? `AI (${a.agent}${a.confidence === "medium" ? ", likely" : ""})` : "human";
+  const lines = [
+    `${r.file}${r.line !== null ? `:${r.line}` : ""}`,
+    `  commit  ${r.commit.sha.slice(0, 7)} by ${r.commit.authorName} on ${r.commit.date.slice(0, 10)} \xB7 written by ${who}`,
+    `  message ${r.commit.message.split("\n")[0]}`,
+    `  ticket  ${r.ticket ?? "none"}`
+  ];
+  if (r.decisions.length === 0) lines.push("  decisions: none recorded for this file");
+  for (const d of r.decisions) {
+    lines.push(
+      `  \u2022 ${d.id} [${d.type}] ${d.question} \u2192 ${d.chosen}`,
+      `    decided by ${d.decided_by}; ${d.approver_claimed ? `approver (claimed): ${d.approver_claimed}` : "unconfirmed approver"}`
+    );
+    if (d.reason) lines.push(`    why: ${d.reason}`);
+  }
+  lines.push(`  ${r.status}`);
+  return lines.join("\n");
+}
+async function runWhy(cwd, arg, o) {
+  const root = await repoRoot(cwd);
+  const result = await whyLocal(root, await loadConfig(root), parseTarget(arg), await realpath3(cwd));
+  return o.json ? JSON.stringify(result, null, 2) : formatWhy(result);
+}
+
+// src/errors.ts
+function formatCliError(e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  return `truthtrail: ${msg.split("\n")[0]}`;
+}
+
+// src/commands/check.ts
+function formatCheck(r) {
+  const lines = [`TruthTrail check \xB7 ticket ${r.ticket ?? "none"} \xB7 ${r.aiCommits}/${r.totalCommits} commits AI-assisted`];
+  for (const i of r.invalid) lines.push(`\u2717 invalid record ${i.path}: ${i.message}`);
+  for (const d of r.decisions) lines.push(`\u2022 ${d.id} [${d.type}] ${d.question} \u2192 ${d.chosen}`);
+  if (r.assumptions.length) lines.push(`\u26A0 ${r.assumptions.length} assumption(s) need confirmation`);
+  for (const m of r.reminders) lines.push(`\u2192 ${m}`);
+  return lines.join("\n");
+}
+async function runCheck(cwd, o) {
+  const root = await repoRoot(cwd);
+  const report = await checkRepo(root, await loadConfig(root), o.base ?? "main");
+  return {
+    output: o.json ? JSON.stringify(report, null, 2) : formatCheck(report),
+    exitCode: report.invalid.length > 0 ? 1 : 0
+  };
+}
+
+// src/commands/pending.ts
+async function runPendingList(cwd) {
+  const items = await listPending(await repoRoot(cwd));
+  if (items.length === 0) return "No pending questions.";
+  return items.map((p) => `#${p.index}  ${p.question} \u2192 ${p.answer}`).join("\n");
+}
+async function runPendingDismiss(cwd, index) {
+  const hit = await removePending(await repoRoot(cwd), index);
+  if (!hit) throw new Error(`No pending question #${index}.`);
+  return `dismissed #${index}: ${hit.question}`;
+}
+
+// src/commands/hook.ts
+async function runHook(event, stdin, cwd) {
+  try {
+    let payload = null;
+    try {
+      payload = stdin.trim() ? JSON.parse(stdin) : null;
+    } catch {
+      payload = null;
+    }
+    const dir = typeof payload?.cwd === "string" ? payload.cwd : cwd;
+    const root = await repoRoot(dir);
+    if (event === "session-start") {
+      return await sessionStartContext(root, await loadConfig(root), await currentBranch(root));
+    }
+    if (event === "capture") {
+      for (const a of extractAskAnswers(payload)) {
+        await appendPending(root, { ...a, at: (/* @__PURE__ */ new Date()).toISOString() });
+      }
+      return "";
+    }
+    const d = await stopDecision(root, payload);
+    return d ? JSON.stringify(d) : "";
+  } catch {
+    return "";
+  }
+}
+async function readStdin() {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+// 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.1.0");
+  program.command("init").description("Set up TruthTrail in this repo (.decisions/, AGENTS.md rules, config)").action(async () => {
+    await runInit(process.cwd(), (l) => console.log(l));
+  });
+  program.command("decide").description("Record a decision (or assumption) for the current ticket").option("--question <text>", "what needed deciding").option("--chosen <text>", "what was picked").option("--options <list>", "choices considered, separated by |").option("--reason <text>", "why").option("--type <type>", "decision | assumption | impact", "decision").option("--ticket <key>", "ticket key (default: from branch name)").option("--files <list>", "affected files, comma separated").option("--approver <name>", "who the user said approved it (never guess)").option("--supersedes <ids>", "ids of older decisions this replaces, comma separated").option("--agent <name>", "AI agent involved").option("--body <text>", "short extra explanation").option("--from-pending <n>", "record a question captured by the Claude Code hook", (v) => Number(v)).action(async (o) => {
+    const r = await runDecide(process.cwd(), o, process.env, /* @__PURE__ */ new Date());
+    console.log(`recorded ${r.id}
+  ${r.path}`);
+  });
+  program.command("list").description("List recorded decisions").option("--ticket <key>", "only this ticket").option("--json", "machine-readable output").action(async (o) => {
+    console.log(await runList(process.cwd(), o));
+  });
+  program.command("why").description("Explain who wrote a file or line, which decisions shaped it, and the ticket").argument("<target>", "file or file:line").option("--json", "machine-readable output").action(async (target, o) => {
+    console.log(await runWhy(process.cwd(), target, o));
+  });
+  program.command("check").description("Check this branch: ticket, decisions, assumptions, AI commits").option("--base <ref>", "branch to compare against", "main").option("--json", "machine-readable output").action(async (o) => {
+    const { output, exitCode } = await runCheck(process.cwd(), o);
+    console.log(output);
+    process.exitCode = exitCode;
+  });
+  const pending = program.command("pending").description("Questions captured by the Claude Code hook, not yet classified");
+  pending.command("list").description("List pending questions").action(async () => console.log(await runPendingList(process.cwd())));
+  pending.command("dismiss").description("Drop a pending question that does not change visible behaviour").argument("<n>", "pending index", (v) => Number(v)).action(async (n) => console.log(await runPendingDismiss(process.cwd(), n)));
+  program.command("hook").description("Claude Code hook entry point (used by the TruthTrail plugin)").argument("<event>", "session-start | capture | stop").action(async (event) => {
+    const out = await runHook(event, await readStdin(), process.cwd());
+    if (out) console.log(out);
+  });
+  return program;
+}
+var isMain = process.argv[1] && /(?:index\.[jt]s|truthtrail)$/.test(process.argv[1]);
+if (isMain) {
+  buildProgram().parseAsync(process.argv).catch((e) => {
+    console.error(formatCliError(e));
+    process.exit(1);
+  });
+}
+export {
+  buildProgram
+};

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "truthtrail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Record the decisions your AI coding agent makes, right next to the code.",
+  "type": "module",
+  "bin": { "truthtrail": "dist/index.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": { "build": "tsup" },
+  "dependencies": { "commander": "^12.1.0", "yaml": "^2.5.0" },
+  "devDependencies": { "@truthtrail/core": "*" },
+  "license": "MIT"
+}