timeline-truth 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Timeline Truth
 
-Status: v0.1.0 public release. MIT licensed. Requires Node.js 22 or newer.
+Status: v0.2.0 public release. MIT licensed. Requires Node.js 22 or newer.
 
 Timeline Truth is a local MCP server for AI-agent TPM workflows: paste PRD/Jira/status notes,
 CSV exports, launch checklists, or rough planning text; get timeline JSON,
@@ -30,8 +30,18 @@ single source. Then summarize the timeline, list gaps and assumptions, and show
 the mermaid_gantt output. Do not infer missing dates or owners.
 ```
 
-The server returns normalized items, gaps such as missing start/end dates, the
-default assumption that dates were not inferred, and portable Mermaid output.
+The server returns normalized items, confidence reasons, grouped follow-up
+questions, gaps such as missing start/end dates, the default assumption that
+dates were not inferred, and portable Mermaid output.
+
+For a quick local smoke test without configuring an MCP client, run the CLI:
+
+```bash
+timeline-truth examples/launch-checklist.md --format review
+```
+
+The CLI reads from stdin when no file is provided, and can print `json`,
+`markdown`, `mermaid_gantt`, `mermaid_timeline`, or `review` output.
 
 For larger Markdown notes, `create_timeline` can parse only selected headings
 and ignore the rest:
@@ -108,6 +118,7 @@ Optional global install:
 
 ```bash
 npm install -g timeline-truth
+timeline-truth examples/launch-checklist.md --format review
 timeline-truth-mcp
 ```
 
@@ -125,7 +136,7 @@ For local development, use the checkout config in
 - `validate_timeline`: report missing dates, owners, unknown dependencies,
   circular dependencies, and impossible sequencing.
 - `render_timeline`: render a normalized timeline as `mermaid_gantt`,
-  `mermaid_timeline`, or `markdown`.
+  `mermaid_timeline`, `markdown`, or `review_report`.
 - `refine_timeline`: apply edits while preserving evidence (`source_refs`) and
   assumptions.
 

package/docs/MCP-SETUP.md

@@ -46,6 +46,7 @@ Optional global install:
 
 ```bash
 npm install -g timeline-truth
+timeline-truth examples/launch-checklist.md --format review
 timeline-truth-mcp
 ```
 
@@ -81,5 +82,7 @@ Useful follow-up calls:
 
 - `validate_timeline` after manual edits or agent refinements.
 - `render_timeline` when you need only Mermaid or Markdown output.
+- `render_timeline` with `review_report` when you need a paste-ready review
+  summary with confidence reasons and grouped follow-up questions.
 - `refine_timeline` when a human answers a gap and you need to preserve
   existing `source_refs`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "timeline-truth",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Open-source MCP server for compiling messy project planning inputs into evidence-preserving timelines.",
   "author": "hilmimuktitama",
   "license": "MIT",
@@ -14,6 +14,7 @@
   "homepage": "https://github.com/hilmimuktitama/timeline-truth#readme",
   "type": "module",
   "bin": {
+    "timeline-truth": "src/cli.js",
     "timeline-truth-mcp": "src/mcp-server.js"
   },
   "files": [

package/src/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { basename, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createTimeline } from "./timeline.js";
+
+const FORMAT_ALIASES = {
+  json: "json",
+  markdown: "markdown",
+  md: "markdown",
+  mermaid: "mermaid_gantt",
+  mermaid_gantt: "mermaid_gantt",
+  gantt: "mermaid_gantt",
+  mermaid_timeline: "mermaid_timeline",
+  timeline: "mermaid_timeline",
+  review: "review_report",
+  review_report: "review_report"
+};
+
+export function parseCliArgs(argv = []) {
+  const options = {
+    inputPath: "-",
+    sourceType: "text",
+    format: "json"
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--type" || arg === "--source-type") {
+      options.sourceType = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg === "--format") {
+      options.format = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg.startsWith("--")) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      options.inputPath = arg;
+    }
+  }
+
+  if (options.inputPath !== "-" && options.sourceType === "text") {
+    options.sourceType = inferSourceType(options.inputPath);
+  }
+
+  return options;
+}
+
+export function runTimelineCli({ argv = process.argv.slice(2), stdin, cwd = process.cwd() } = {}) {
+  const options = parseCliArgs(argv);
+  if (options.help) return usage();
+
+  const content = options.inputPath === "-"
+    ? stdin ?? readFileSync(0, "utf8")
+    : readFileSync(resolve(cwd, options.inputPath), "utf8");
+  const result = createTimeline({
+    sources: [
+      {
+        id: options.inputPath === "-" ? "stdin" : basename(options.inputPath),
+        type: options.sourceType,
+        path: options.inputPath === "-" ? undefined : options.inputPath,
+        content
+      }
+    ]
+  });
+
+  return formatCliResult(result, options.format);
+}
+
+export function formatCliResult(result, format = "json") {
+  const normalizedFormat = normalizeFormat(format);
+  if (normalizedFormat === "json") return JSON.stringify(result, null, 2);
+  if (normalizedFormat === "markdown") return result.renders.markdown.trimEnd();
+  if (normalizedFormat === "review_report") return result.renders.review_report.trimEnd();
+  if (normalizedFormat === "mermaid_timeline") return result.renders.mermaid_timeline.trimEnd();
+  return result.renders.mermaid_gantt.trimEnd();
+}
+
+function normalizeFormat(format) {
+  const normalized = String(format || "json").toLowerCase();
+  const mapped = FORMAT_ALIASES[normalized];
+  if (!mapped) {
+    throw new Error(`Unsupported format "${format}". Use json, markdown, mermaid_gantt, mermaid_timeline, or review.`);
+  }
+  return mapped;
+}
+
+function inferSourceType(inputPath) {
+  const extension = extname(inputPath).toLowerCase();
+  if (extension === ".md" || extension === ".markdown") return "markdown";
+  if (extension === ".csv") return "csv";
+  if (extension === ".json") return "json";
+  return "text";
+}
+
+function requireValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`Missing value for ${option}.`);
+  }
+  return value;
+}
+
+function usage() {
+  return [
+    "Usage: timeline-truth [file] [--type text|markdown|csv|json] [--format json|markdown|mermaid_gantt|mermaid_timeline|review]",
+    "",
+    "Reads stdin when no file is provided."
+  ].join("\n");
+}
+
+const isDirectRun = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isDirectRun) {
+  try {
+    process.stdout.write(`${runTimelineCli()}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/mcp-server.js

@@ -8,7 +8,7 @@ import { callTimelineTool, listTimelineTools } from "./mcp-tools.js";
 const server = new Server(
   {
     name: "timeline-truth",
-    version: "0.1.0"
+    version: "0.2.0"
   },
   {
     capabilities: {

package/src/mcp-tools.js

@@ -79,7 +79,7 @@ export function listTimelineTools() {
     },
     {
       name: "render_timeline",
-      description: "Render a normalized timeline as Mermaid Gantt, Mermaid timeline, or compact Markdown.",
+      description: "Render a normalized timeline as Mermaid Gantt, Mermaid timeline, compact Markdown, or a review report.",
       inputSchema: {
         type: "object",
         required: ["timeline"],
@@ -88,7 +88,7 @@ export function listTimelineTools() {
           timeline: TIMELINE_SCHEMA,
           format: {
             type: "string",
-            enum: ["mermaid_gantt", "mermaid_timeline", "markdown"],
+            enum: ["mermaid_gantt", "mermaid_timeline", "markdown", "review_report"],
             default: "mermaid_gantt"
           }
         }

package/src/timeline.js

@@ -17,7 +17,7 @@ export function createTimeline(input = {}) {
     gaps: [],
     render: {
       audience: "TPM/PM",
-      defaultFormats: ["mermaid_gantt", "mermaid_timeline", "markdown"]
+      defaultFormats: ["mermaid_gantt", "mermaid_timeline", "markdown", "review_report"]
     }
   });
   const validation = validateTimeline(timeline);
@@ -26,17 +26,20 @@ export function createTimeline(input = {}) {
     gaps: validation.gaps,
     issues: validation.issues
   };
+  const followups = buildFollowups(validatedTimeline);
 
   return {
     timeline: validatedTimeline,
     assumptions: validatedTimeline.assumptions,
     gaps: validatedTimeline.gaps,
     issues: validation.issues,
+    followups,
     noise_report: noiseReport,
     renders: {
       mermaid_gantt: renderTimeline(validatedTimeline, { format: "mermaid_gantt" }),
       mermaid_timeline: renderTimeline(validatedTimeline, { format: "mermaid_timeline" }),
-      markdown: renderTimeline(validatedTimeline, { format: "markdown" })
+      markdown: renderTimeline(validatedTimeline, { format: "markdown" }),
+      review_report: renderTimeline(validatedTimeline, { format: "review_report" })
     }
   };
 }
@@ -71,11 +74,13 @@ export function validateTimeline(timeline = {}) {
   for (const item of normalized.items) {
     for (const dependency of item.dependencies) {
       if (!normalized.items.some((candidate) => candidate.title === dependency)) {
+        const suggestions = suggestDependencyTitles(normalized.items, dependency);
         issues.push({
           type: "unknown_dependency",
           severity: "warning",
           itemTitle: item.title,
           dependency,
+          suggestions,
           message: `Dependency "${dependency}" was not found in the timeline.`
         });
       }
@@ -122,6 +127,10 @@ export function renderTimeline(timeline = {}, options = {}) {
     return renderMarkdown(normalized);
   }
 
+  if (format === "review_report") {
+    return renderReviewReport(normalized);
+  }
+
   return renderMermaidGantt(normalized);
 }
 
@@ -175,7 +184,13 @@ function parseSource(source, index, importedAssumptions, input, noiseReport) {
 }
 
 function parseJsonSource(source, importedAssumptions) {
-  const parsed = typeof source.content === "string" ? JSON.parse(source.content) : source.content;
+  let parsed;
+  try {
+    parsed = typeof source.content === "string" ? JSON.parse(source.content) : source.content;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Unable to parse JSON source "${source.id}": ${detail}`);
+  }
   const rawItems = Array.isArray(parsed) ? parsed : parsed.items ?? [];
 
   if (Array.isArray(parsed.assumptions)) {
@@ -311,7 +326,10 @@ function parseTextLine(line, sourceId, lineNumber) {
     owner,
     status,
     dependencies,
-    confidence: dates.length > 0 ? 0.75 : 0.45
+    confidence: dates.length > 0 ? 0.75 : 0.45,
+    confidence_reason: dates.length > 0
+      ? "Exact date evidence found in source text."
+      : "No exact dates found; timeline placement needs human follow-up."
   };
 
   return normalizeItem(item, [{ sourceId, line: lineNumber, text: trimmed }]);
@@ -406,7 +424,12 @@ function markdownRecordToItem(record, heading) {
     time_window: fuzzyTarget,
     date_text: fuzzyTarget,
     exact_date_needed: Boolean(fuzzyTarget),
-    confidence: target ? 0.7 : 0.55
+    confidence: target ? 0.7 : 0.55,
+    confidence_reason: fuzzyTarget
+      ? "Fuzzy date text was preserved for human review."
+      : target
+        ? "Exact target date evidence found in Markdown table."
+        : "No target date found in Markdown table row."
   };
 }
 
@@ -421,6 +444,7 @@ function normalizeTimeline(timeline = {}) {
     milestones,
     assumptions: Array.isArray(timeline.assumptions) ? [...timeline.assumptions] : [],
     gaps: Array.isArray(timeline.gaps) ? [...timeline.gaps] : [],
+    issues: Array.isArray(timeline.issues) ? [...timeline.issues] : [],
     render: timeline.render && typeof timeline.render === "object" ? { ...timeline.render } : {}
   };
 }
@@ -446,6 +470,9 @@ function normalizeItem(item = {}, sourceRefs = []) {
     status: blankToUndefined(item.status) || "unknown",
     dependencies: dependencies.map((dependency) => String(dependency).trim()).filter(Boolean),
     confidence: typeof item.confidence === "number" ? item.confidence : 0.6,
+    confidence_reason: typeof item.confidence_reason === "string"
+      ? item.confidence_reason
+      : deriveConfidenceReason(item),
     source_refs: normalizeSourceRefs(sourceRefs)
   };
 }
@@ -513,6 +540,24 @@ function dedupeCycles(cycles) {
   });
 }
 
+function suggestDependencyTitles(items, dependency) {
+  const dependencyKey = normalizeDependencyKey(dependency);
+  if (!dependencyKey) return [];
+
+  return items
+    .filter((item) => {
+      const titleKey = normalizeDependencyKey(item.title);
+      const idKey = normalizeDependencyKey(item.id);
+      return titleKey === dependencyKey || idKey === dependencyKey;
+    })
+    .map((item) => item.title)
+    .slice(0, 3);
+}
+
+function normalizeDependencyKey(value) {
+  return String(value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
 function renderMermaidGantt(timeline) {
   const lines = ["gantt", "  title Project Timeline", "  dateFormat YYYY-MM-DD", "  axisFormat %b %d", "  section Plan"];
 
@@ -572,6 +617,107 @@ function renderMarkdown(timeline) {
   return `${lines.join("\n")}\n`;
 }
 
+function renderReviewReport(timeline) {
+  const followups = buildFollowups(timeline);
+  const lines = ["## Timeline Review", "", "### Items"];
+
+  for (const item of timeline.items) {
+    const window = item.start ? `${item.start}${item.end ? ` to ${item.end}` : item.duration ? ` for ${item.duration}` : ""}` : item.time_window || "date needed";
+    lines.push(`- **${item.title}** (${item.type}, ${item.status}) - ${window}${item.owner ? ` - owner: ${item.owner}` : ""}`);
+    lines.push(`  - Confidence: ${item.confidence} - ${item.confidence_reason}`);
+    if (item.source_refs.length > 0) {
+      lines.push(`  - Source: ${formatSourceRef(item.source_refs[0])}`);
+    }
+  }
+
+  if (timeline.gaps.length > 0) {
+    lines.push("", "### Follow-Up Questions");
+    for (const followup of followups.all) {
+      lines.push(`- ${followup.itemTitle}${followup.owner ? ` (${followup.owner})` : ""}: ${followup.question}`);
+    }
+  }
+
+  if (timeline.issues.length > 0) {
+    lines.push("", "### Issues");
+    for (const issue of timeline.issues) {
+      const suggestions = issue.suggestions?.length ? ` Suggestions: ${issue.suggestions.join(", ")}.` : "";
+      lines.push(`- ${issue.severity}: ${issue.message}${suggestions}`);
+    }
+  }
+
+  if (timeline.assumptions.length > 0) {
+    lines.push("", "### Assumptions");
+    for (const assumption of timeline.assumptions) {
+      lines.push(`- ${assumption}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function buildFollowups(timeline) {
+  const byTitle = new Map(timeline.items.map((item) => [item.title, item]));
+  const gapFollowups = timeline.gaps.map((gap) => {
+    const item = byTitle.get(gap.itemTitle);
+    return {
+      itemTitle: gap.itemTitle,
+      field: gap.field,
+      owner: item?.owner,
+      question: gap.question,
+      source_refs: gap.source_refs
+    };
+  });
+  const dependencyFollowups = timeline.issues
+    .filter((issue) => issue.type === "unknown_dependency")
+    .map((issue) => {
+      const item = byTitle.get(issue.itemTitle);
+      const suggestions = issue.suggestions?.length
+        ? ` Did you mean ${issue.suggestions.join(", ")}?`
+        : "";
+      return {
+        itemTitle: issue.itemTitle,
+        field: "dependency",
+        dependency: issue.dependency,
+        owner: item?.owner,
+        question: `Confirm the dependency "${issue.dependency}" or add it to the timeline.${suggestions}`,
+        source_refs: item?.source_refs ?? []
+      };
+    });
+  const all = [...gapFollowups, ...dependencyFollowups];
+  const dateFollowups = all.filter((followup) => ["start", "end", "exact_date"].includes(followup.field));
+
+  return {
+    all,
+    by_field: groupBy(all, (followup) => followup.field),
+    by_owner: groupBy(all, (followup) => followup.owner || "Unassigned"),
+    by_date: groupBy(dateFollowups, (followup) => followup.field),
+    by_dependency: groupBy(dependencyFollowups, (followup) => followup.dependency)
+  };
+}
+
+function groupBy(values, keyFn) {
+  return values.reduce((groups, value) => {
+    const key = keyFn(value);
+    groups[key] = groups[key] || [];
+    groups[key].push(value);
+    return groups;
+  }, {});
+}
+
+function deriveConfidenceReason(item) {
+  if (item.time_window || item.date_text) return "Fuzzy date text was preserved for human review.";
+  if (item.start || item.end || item.duration) return "Structured date evidence was supplied.";
+  return "No date evidence was supplied.";
+}
+
+function formatSourceRef(sourceRef) {
+  const parts = [sourceRef.sourceId];
+  if (sourceRef.path) parts.push(sourceRef.path);
+  if (sourceRef.heading) parts.push(`heading "${sourceRef.heading}"`);
+  if (sourceRef.line) parts.push(`line ${sourceRef.line}`);
+  return parts.filter(Boolean).join(", ");
+}
+
 function parseCsv(content) {
   const rows = [];
   let row = [];