feat(review): accept/skip TUI closes core loop — hook → proposer → review → TRACE.md

Author: shandar

.claude/settings.json

@@ -0,0 +1 @@
+{"hooks":{"PostToolUse":[{"matcher":"*","hooks":[{"type":"command","command":"node /Users/shandarjunaid/Downloads/Trace/dist/proposer.js"}]}]}}

.trace/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(update-config)"
+    ]
+  }
+}

.trace/pending.jsonl

@@ -299,3 +299,7 @@ This is where TRACE has to surface something that even Anthropic finds interesti
 ---
 
 *Plan ready. Execute mode next.*
+
+## Decision Log
+
+- Confirmed README.md exists with TRACE as the project title, establishing baseline repo documentation.

TRACE.md

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { review } from "./review.js";
 
 const TEMPLATE = `# TRACE — Living PRD
 
@@ -72,4 +73,11 @@ program
     }
   });
 
-program.parse();
+program
+  .command("review")
+  .description("Review pending proposed edits and append accepted ones to TRACE.md.")
+  .action(async () => {
+    await review(process.cwd());
+  });
+
+program.parseAsync();

src/cli.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { readFileSync, appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const SYSTEM_PROMPT =
+  'You are a PRD updater. Given a Claude Code tool event and the current TRACE.md, propose ONE short edit — a single sentence to add to the Decision Log section. Return ONLY a JSON object: {"section": "Decision Log", "edit": "<one sentence>", "confidence": 0.0-1.0}. No preamble. No markdown.';
+
+const MODEL = "claude-opus-4-7";
+const API_URL = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_VERSION = "2023-06-01";
+
+interface HookEvent {
+  cwd?: string;
+  [k: string]: unknown;
+}
+
+interface AnthropicContentBlock {
+  type: string;
+  text?: string;
+}
+
+interface AnthropicResponse {
+  content?: AnthropicContentBlock[];
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main(): Promise<void> {
+  const raw = await readStdin();
+  if (!raw.trim()) return;
+
+  let event: HookEvent;
+  try {
+    event = JSON.parse(raw) as HookEvent;
+  } catch {
+    return;
+  }
+
+  const cwd = event.cwd;
+  if (typeof cwd !== "string" || cwd.length === 0) return;
+
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) return;
+
+  let traceMd: string;
+  try {
+    traceMd = readFileSync(resolve(cwd, "TRACE.md"), "utf8");
+  } catch {
+    return;
+  }
+
+  const userContent = `<event>\n${JSON.stringify(event, null, 2)}\n</event>\n\n<trace_md>\n${traceMd}\n</trace_md>`;
+
+  const res = await fetch(API_URL, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": ANTHROPIC_VERSION,
+    },
+    body: JSON.stringify({
+      model: MODEL,
+      max_tokens: 300,
+      system: SYSTEM_PROMPT,
+      messages: [{ role: "user", content: userContent }],
+    }),
+  });
+
+  if (!res.ok) return;
+
+  const data = (await res.json()) as AnthropicResponse;
+  const text = data.content?.[0]?.text?.trim();
+  if (!text) return;
+
+  let normalized: string;
+  try {
+    normalized = JSON.stringify(JSON.parse(text));
+  } catch {
+    return;
+  }
+
+  const pendingPath = resolve(cwd, ".trace/pending.jsonl");
+  appendFileSync(pendingPath, normalized + "\n");
+}
+
+main().catch(() => {
+  // Silent. Never block the Claude Code session.
+});

src/proposer.ts

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+interface PendingEdit {
+  section: string;
+  edit: string;
+  confidence: number;
+}
+
+function parsePending(raw: string): PendingEdit[] {
+  const out: PendingEdit[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const obj = JSON.parse(trimmed) as Partial<PendingEdit>;
+      if (typeof obj.section === "string" && typeof obj.edit === "string") {
+        out.push({
+          section: obj.section,
+          edit: obj.edit,
+          confidence:
+            typeof obj.confidence === "number" ? obj.confidence : 0,
+        });
+      }
+    } catch {
+      // skip malformed line
+    }
+  }
+  return out;
+}
+
+function appendToDecisionLog(tracePath: string, edit: string): void {
+  let doc = readFileSync(tracePath, "utf8");
+  if (!doc.endsWith("\n")) doc += "\n";
+  const bullet = `- ${edit}\n`;
+
+  const heading = /^##\s+Decision Log\b.*$/im.exec(doc);
+  if (!heading) {
+    writeFileSync(tracePath, `${doc}\n## Decision Log\n\n${bullet}`, "utf8");
+    return;
+  }
+
+  const headingLineEnd = doc.indexOf("\n", heading.index) + 1;
+  const rest = doc.slice(headingLineEnd);
+  const nextHeading = /^##\s+/m.exec(rest);
+  const sectionEnd = nextHeading
+    ? headingLineEnd + nextHeading.index
+    : doc.length;
+
+  const before = doc.slice(0, headingLineEnd);
+  const body = doc.slice(headingLineEnd, sectionEnd).replace(/\s*$/, "");
+  const after = doc.slice(sectionEnd);
+
+  const newBody = body === "" ? `\n${bullet}` : `${body}\n${bullet}`;
+  const separator = after ? "\n" : "";
+  writeFileSync(tracePath, before + newBody + separator + after, "utf8");
+}
+
+export async function review(cwd: string): Promise<void> {
+  const pendingPath = resolve(cwd, ".trace/pending.jsonl");
+  const tracePath = resolve(cwd, "TRACE.md");
+
+  if (!existsSync(tracePath)) {
+    console.error(
+      "trace: no TRACE.md in current directory. Run `trace init` first.",
+    );
+    process.exit(1);
+  }
+
+  if (!existsSync(pendingPath)) {
+    console.log("trace: no pending edits.");
+    return;
+  }
+
+  const edits = parsePending(readFileSync(pendingPath, "utf8"));
+  if (edits.length === 0) {
+    console.log("trace: no pending edits.");
+    return;
+  }
+
+  const rl = createInterface({ input, output });
+  let accepted = 0;
+  let skipped = 0;
+  let i = 0;
+  let aborted = false;
+
+  try {
+    for (; i < edits.length; i++) {
+      const { section, edit, confidence } = edits[i];
+      console.log("");
+      console.log(`── proposal ${i + 1} of ${edits.length} ──`);
+      console.log(`section:    ${section}`);
+      console.log(`confidence: ${confidence.toFixed(2)}`);
+      console.log(`edit:       ${edit}`);
+      console.log("");
+
+      let answer: string;
+      try {
+        answer = (await rl.question("[a]ccept / [s]kip? "))
+          .trim()
+          .toLowerCase();
+      } catch {
+        console.log("\n→ input closed. Remaining proposals kept in queue.");
+        aborted = true;
+        break;
+      }
+
+      if (answer === "a" || answer === "accept") {
+        appendToDecisionLog(tracePath, edit);
+        accepted++;
+        console.log("→ accepted, appended to Decision Log.");
+      } else {
+        skipped++;
+        console.log("→ skipped.");
+      }
+    }
+  } finally {
+    rl.close();
+  }
+
+  if (aborted) {
+    const remaining = edits
+      .slice(i)
+      .map((e) => JSON.stringify(e))
+      .join("\n");
+    writeFileSync(
+      pendingPath,
+      remaining.length ? remaining + "\n" : "",
+      "utf8",
+    );
+    console.log("");
+    console.log(
+      `trace: reviewed ${i} of ${edits.length} — ${accepted} accepted, ${skipped} skipped. ${edits.length - i} kept in queue.`,
+    );
+    return;
+  }
+
+  writeFileSync(pendingPath, "", "utf8");
+  console.log("");
+  console.log(
+    `trace: reviewed ${edits.length} — ${accepted} accepted, ${skipped} skipped. Queue cleared.`,
+  );
+}