timeline-truth 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,6 @@
 # Timeline Truth
 
-Status: v0.2 adoption release in progress. 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,
@@ -31,8 +30,44 @@ 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:
+
+```json
+{
+  "sources": [
+    {
+      "id": "program-note",
+      "type": "markdown",
+      "path": "docs/program.md",
+      "content": "..."
+    }
+  ],
+  "markdown": {
+    "sections": ["Timeline", "Follow-Ups"],
+    "ignoreFrontmatter": true
+  }
+}
+```
+
+Markdown tables under those headings are parsed into items. Fuzzy targets such
+as `W3-W4 May 2026` are preserved as `time_window`/`date_text` and flagged with
+an `exact_date` gap instead of being converted into invented dates. The response
+also includes `noise_report.ignored` counts for skipped frontmatter, prose, and
+table rows without target dates.
 
 ## Why This Exists
 
@@ -66,7 +101,7 @@ npm install
 node src/mcp-server.js
 ```
 
-Npm package config, after the npm package is published:
+Npm package config:
 
 ```json
 {
@@ -79,9 +114,20 @@ Npm package config, after the npm package is published:
 }
 ```
 
-Important: the npm package install path works only after `timeline-truth` is
-published to npm. Before the npm package is published, use the local checkout
-config in [docs/MCP-SETUP.md](docs/MCP-SETUP.md).
+Optional global install:
+
+```bash
+npm install -g timeline-truth
+timeline-truth examples/launch-checklist.md --format review
+timeline-truth-mcp
+```
+
+If your global npm bin directory is on `PATH`, you can also configure the MCP
+server with `"command": "timeline-truth-mcp"`. The `npx --package` config above
+is the most portable option because it does not depend on global shell setup.
+
+For local development, use the checkout config in
+[docs/MCP-SETUP.md](docs/MCP-SETUP.md).
 
 ## MCP Tools
 
@@ -90,7 +136,7 @@ config in [docs/MCP-SETUP.md](docs/MCP-SETUP.md).
 - `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.
 
@@ -107,9 +153,9 @@ Each example has a compact expected-output JSON file and is covered by tests.
 
 ## Current limitations
 
-- Text and Markdown parsing is heuristic. It works best when each planning item
-  is on its own line.
-- Markdown headings are ignored and task-list markers are stripped, but rich
+- Text parsing is heuristic. It works best when each planning item is on its own
+  line.
+- Markdown parsing supports heading filters and simple pipe tables, but rich
   nested documents are not fully parsed.
 - CSV and JSON are more reliable than free-form notes when exact fields matter.
 - There are no Jira, Confluence, Slack, or hosted imports in this release.

package/docs/MCP-SETUP.md

@@ -26,7 +26,7 @@ npm install
 
 ## Npm Package
 
-Use this after the `timeline-truth` npm package is published:
+Use the published `timeline-truth` package:
 
 ```json
 {
@@ -39,8 +39,33 @@ Use this after the `timeline-truth` npm package is published:
 }
 ```
 
-Before publish, `npx --package=timeline-truth timeline-truth-mcp` will fail
-because the package is not yet available from the public registry.
+This is the recommended package config because it does not require a global npm
+install or depend on the user's global npm bin directory being on `PATH`.
+
+Optional global install:
+
+```bash
+npm install -g timeline-truth
+timeline-truth examples/launch-checklist.md --format review
+timeline-truth-mcp
+```
+
+With the global package installed and available on `PATH`, the MCP config can
+call the package binary directly:
+
+```json
+{
+  "mcpServers": {
+    "timeline-truth": {
+      "command": "timeline-truth-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If you need to test local changes before publishing a new version, use the local
+checkout config above.
 
 ## Agent Prompt
 
@@ -57,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/docs/RELEASE.md

@@ -2,15 +2,22 @@
 
 Use this checklist before publishing a public version of `timeline-truth`.
 
+## Current Release Notes
+
+- Markdown ingestion now ignores frontmatter by default, parses configured
+  headings, supports simple pipe tables, preserves fuzzy time windows, enriches
+  source refs, and reports ignored content through `noise_report`.
+- This release intentionally does not include CLI file mode, TPM validation
+  profiles, or dependency matching by external IDs.
+
 ## Verify Package Name
 
 ```bash
 npm view timeline-truth version
 ```
 
-Expected before first publish: npm returns `404 Not Found`.
-
-Expected after publish: npm returns the latest published version.
+Expected result: npm returns the latest published version. Before publishing a
+new release, confirm whether the version in `package.json` needs to be bumped.
 
 ## Verify Local Quality
 

package/package.json

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

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

@@ -6,6 +6,7 @@ const SOURCE_SCHEMA = {
   additionalProperties: true,
   properties: {
     id: { type: "string", description: "Stable source identifier used in source_refs." },
+    path: { type: "string", description: "Optional file path to preserve in source_refs." },
     type: { type: "string", enum: ["text", "markdown", "csv", "json"], default: "text" },
     content: {
       description: "Pasted text/file content. JSON sources may pass a JSON string or object.",
@@ -42,6 +43,23 @@ export function listTimelineTools() {
             type: "array",
             minItems: 1,
             items: SOURCE_SCHEMA
+          },
+          markdown: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              sections: {
+                type: "array",
+                items: { type: "string" },
+                description:
+                  "Markdown headings to parse. Defaults to Timeline, Milestones, Next, Risks And Blockers, and Follow-Ups."
+              },
+              ignoreFrontmatter: {
+                type: "boolean",
+                default: true,
+                description: "Ignore YAML frontmatter before parsing Markdown content."
+              }
+            }
           }
         }
       }
@@ -61,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"],
@@ -70,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"
           }
         }
@@ -108,7 +126,7 @@ export function listTimelineTools() {
 export function callTimelineTool(name, args = {}) {
   switch (name) {
     case "create_timeline":
-      return jsonContent(createTimeline({ sources: args.sources }));
+      return jsonContent(createTimeline({ sources: args.sources, markdown: args.markdown }));
     case "validate_timeline":
       return jsonContent(validateTimeline(args.timeline));
     case "render_timeline":

package/src/timeline.js

@@ -1,9 +1,13 @@
 const DATE_PATTERN = /\b\d{4}-\d{2}-\d{2}\b/g;
+const DEFAULT_MARKDOWN_SECTIONS = ["Timeline", "Milestones", "Next", "Risks And Blockers", "Follow-Ups"];
 
 export function createTimeline(input = {}) {
   const sources = Array.isArray(input.sources) ? input.sources : [];
   const importedAssumptions = [];
-  const items = sources.flatMap((source, index) => parseSource(source, index, importedAssumptions));
+  const noiseReport = createNoiseReport();
+  const items = sources.flatMap((source, index) =>
+    parseSource(source, index, importedAssumptions, input, noiseReport)
+  );
   const timeline = normalizeTimeline({
     items,
     assumptions: [
@@ -13,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);
@@ -22,16 +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" })
     }
   };
 }
@@ -42,11 +50,15 @@ export function validateTimeline(timeline = {}) {
   const issues = [];
 
   for (const item of normalized.items) {
-    if (!item.start) {
+    if (item.exact_date_needed) {
+      gaps.push(makeGap(item, "exact_date", "Exact date needed before rendering this fuzzy time window."));
+    }
+
+    if (!item.start && !item.time_window) {
       gaps.push(makeGap(item, "start", "Missing start date. Ask for the planned start date instead of inferring it."));
     }
 
-    if (!item.end && !item.duration && item.type !== "milestone") {
+    if (!item.end && !item.duration && !item.time_window && item.type !== "milestone") {
       gaps.push(makeGap(item, "end", "Missing end date or duration for a non-milestone item."));
     }
 
@@ -62,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.`
         });
       }
@@ -113,6 +127,10 @@ export function renderTimeline(timeline = {}, options = {}) {
     return renderMarkdown(normalized);
   }
 
+  if (format === "review_report") {
+    return renderReviewReport(normalized);
+  }
+
   return renderMermaidGantt(normalized);
 }
 
@@ -142,11 +160,12 @@ export function refineTimeline(timeline = {}, refinement = {}) {
   };
 }
 
-function parseSource(source, index, importedAssumptions) {
+function parseSource(source, index, importedAssumptions, input, noiseReport) {
   const normalizedSource = {
     id: source?.id || `source-${index + 1}`,
     type: source?.type || "text",
-    content: source?.content ?? ""
+    content: source?.content ?? "",
+    path: source?.path || source?.file_path || source?.filePath
   };
 
   if (normalizedSource.type === "json") {
@@ -157,11 +176,21 @@ function parseSource(source, index, importedAssumptions) {
     return parseCsvSource(normalizedSource);
   }
 
+  if (normalizedSource.type === "markdown") {
+    return parseMarkdownSource(normalizedSource, input?.markdown, noiseReport);
+  }
+
   return parseTextSource(normalizedSource);
 }
 
 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)) {
@@ -197,6 +226,85 @@ function parseTextSource(source) {
     .filter(Boolean);
 }
 
+function parseMarkdownSource(source, markdownOptions = {}, noiseReport = createNoiseReport()) {
+  const lines = String(source.content).split(/\r?\n/);
+  const allowedHeadings = getAllowedMarkdownHeadings(markdownOptions);
+  const hasAllowedHeadings = markdownHasAllowedHeadings(lines, allowedHeadings);
+  const items = [];
+  let currentHeading;
+  let inFrontmatter = markdownOptions?.ignoreFrontmatter === false ? false : lines[0]?.trim() === "---";
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+
+    if (inFrontmatter) {
+      noiseReport.ignored.frontmatter_lines += 1;
+      if (index > 0 && trimmed === "---") inFrontmatter = false;
+      continue;
+    }
+
+    const heading = parseMarkdownHeading(trimmed);
+    if (heading) {
+      currentHeading = heading;
+      continue;
+    }
+
+    if (!trimmed) continue;
+
+    const inAllowedSection = !hasAllowedHeadings || allowedHeadings.has(normalizeHeading(currentHeading));
+    if (!inAllowedSection) {
+      noiseReport.ignored.prose_lines += 1;
+      continue;
+    }
+
+    if (isMarkdownTableLine(trimmed)) {
+      const table = parseMarkdownTable(lines, index);
+      if (!table) {
+        noiseReport.ignored.prose_lines += 1;
+        continue;
+      }
+
+      for (const row of table.rows) {
+        const item = markdownRecordToItem(row.record, currentHeading);
+        if (!item) {
+          noiseReport.ignored.table_rows_without_dates += row.hasDate ? 0 : 1;
+          continue;
+        }
+
+        if (!row.hasDate) noiseReport.ignored.table_rows_without_dates += 1;
+        items.push(
+          normalizeItem(item, [
+            compactObject({
+              sourceId: source.id,
+              path: source.path,
+              heading: currentHeading,
+              tableRow: row.tableRow,
+              line: row.line,
+              text: row.text
+            })
+          ])
+        );
+      }
+
+      index = table.endIndex;
+      continue;
+    }
+
+    const parsedLine = parseTextLine(line, source.id, index + 1);
+    if (parsedLine) {
+      parsedLine.source_refs = parsedLine.source_refs.map((sourceRef) =>
+        compactObject({ ...sourceRef, path: source.path, heading: currentHeading })
+      );
+      items.push(parsedLine);
+    } else {
+      noiseReport.ignored.prose_lines += 1;
+    }
+  }
+
+  return items;
+}
+
 function parseTextLine(line, sourceId, lineNumber) {
   const trimmed = normalizePlanningLine(line);
   if (!trimmed) return null;
@@ -218,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 }]);
@@ -292,6 +403,36 @@ function csvRecordToItem(record) {
   };
 }
 
+function markdownRecordToItem(record, heading) {
+  const title =
+    valueFromRecord(record, ["item", "follow_up", "follow-up", "followup", "task", "milestone", "risk", "blocker"]) ||
+    valueFromRecord(record, ["title", "name"]);
+  if (!title) return null;
+
+  const target = valueFromRecord(record, ["target", "date", "when", "time_window", "window"]);
+  const dates = extractExactDates(target);
+  const fuzzyTarget = target && dates.length === 0 ? target : undefined;
+
+  return {
+    title,
+    type: normalizeHeading(heading) === "milestones" || record.type === "milestone" ? "milestone" : "task",
+    start: dates[0],
+    end: dates[1],
+    owner: valueFromRecord(record, ["owner", "assignee"]),
+    status: valueFromRecord(record, ["status"]) || "planned",
+    dependencies: valueFromRecord(record, ["dependencies", "depends_on", "depends on"]),
+    time_window: fuzzyTarget,
+    date_text: fuzzyTarget,
+    exact_date_needed: Boolean(fuzzyTarget),
+    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."
+  };
+}
+
 function normalizeTimeline(timeline = {}) {
   const items = Array.isArray(timeline.items)
     ? timeline.items.map((item) => normalizeItem(item, item.source_refs))
@@ -303,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 } : {}
   };
 }
@@ -321,10 +463,16 @@ function normalizeItem(item = {}, sourceRefs = []) {
     start: blankToUndefined(item.start),
     end: blankToUndefined(item.end),
     duration: blankToUndefined(item.duration),
+    time_window: blankToUndefined(item.time_window),
+    date_text: blankToUndefined(item.date_text),
+    exact_date_needed: Boolean(item.exact_date_needed),
     owner: blankToUndefined(item.owner),
     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)
   };
 }
@@ -392,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"];
 
@@ -451,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 = [];
@@ -503,6 +770,115 @@ function blankToUndefined(value) {
   return normalized === "" ? undefined : normalized;
 }
 
+function createNoiseReport() {
+  return {
+    ignored: {
+      frontmatter_lines: 0,
+      prose_lines: 0,
+      table_rows_without_dates: 0
+    }
+  };
+}
+
+function getAllowedMarkdownHeadings(options = {}) {
+  const sections = Array.isArray(options?.sections) && options.sections.length > 0
+    ? options.sections
+    : DEFAULT_MARKDOWN_SECTIONS;
+  return new Set(sections.map((section) => normalizeHeading(section)));
+}
+
+function markdownHasAllowedHeadings(lines, allowedHeadings) {
+  return lines.some((line) => {
+    const heading = parseMarkdownHeading(line.trim());
+    return heading && allowedHeadings.has(normalizeHeading(heading));
+  });
+}
+
+function parseMarkdownHeading(line) {
+  const match = line.match(/^#{1,6}\s+(.+?)\s*#*$/);
+  return match ? match[1].trim() : undefined;
+}
+
+function normalizeHeading(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/&/g, "and")
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function isMarkdownTableLine(line) {
+  return /^\|.*\|\s*$/.test(line);
+}
+
+function parseMarkdownTable(lines, startIndex) {
+  const header = parseMarkdownTableCells(lines[startIndex]);
+  const separator = parseMarkdownTableCells(lines[startIndex + 1]);
+  if (header.length === 0 || !isMarkdownSeparatorRow(separator)) return null;
+
+  const headers = header.map((cell) => normalizeHeader(cell));
+  const rows = [];
+  let index = startIndex + 2;
+  let tableRow = 1;
+
+  while (index < lines.length && isMarkdownTableLine(lines[index].trim())) {
+    const cells = parseMarkdownTableCells(lines[index]);
+    const record = {};
+    headers.forEach((column, columnIndex) => {
+      record[column] = cells[columnIndex] ?? "";
+    });
+
+    const target = valueFromRecord(record, ["target", "date", "when", "time_window", "window"]);
+    rows.push({
+      record,
+      tableRow,
+      line: index + 1,
+      text: lines[index].trim(),
+      hasDate: extractExactDates(target).length > 0 || Boolean(blankToUndefined(target))
+    });
+    tableRow += 1;
+    index += 1;
+  }
+
+  return {
+    rows,
+    endIndex: index - 1
+  };
+}
+
+function parseMarkdownTableCells(line = "") {
+  const trimmed = String(line).trim();
+  if (!isMarkdownTableLine(trimmed)) return [];
+  return trimmed
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((cell) => cell.trim());
+}
+
+function isMarkdownSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell.trim()));
+}
+
+function valueFromRecord(record, names) {
+  for (const name of names) {
+    const normalized = normalizeHeader(name);
+    const value = blankToUndefined(record[normalized]);
+    if (value) return value;
+  }
+
+  return undefined;
+}
+
+function extractExactDates(value) {
+  return [...String(value || "").matchAll(DATE_PATTERN)].map((match) => match[0]);
+}
+
+function compactObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+
 function escapeMermaidText(value) {
   return String(value).replace(/[:#;]/g, "-").trim();
 }