timeline-truth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hilmi Muktitama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Timeline Truth
+
+Status: v0.2 adoption release in progress. 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,
+validation gaps, assumptions, and Mermaid/Markdown renders.
+
+It is intentionally narrow. Timeline Truth does not invent missing dates,
+owners, or dependencies. It preserves `source_refs` and makes planning
+uncertainty visible so humans can review the timeline instead of trusting a
+confident rewrite.
+
+## First Use
+
+Use it when your planning input looks like this:
+
+```text
+Discovery: 2026-06-01 to 2026-06-05 owner PM status planned
+API contract: starts 2026-06-06 duration 4d owner Platform depends on Discovery
+Checkout QA: owner QA depends on API contract
+Launch decision milestone on 2026-06-17 owner PM
+```
+
+Ask your agent:
+
+```text
+Use the timeline-truth MCP server. Call create_timeline with these notes as a
+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.
+
+## Why This Exists
+
+Most timeline tools assume the plan is already structured. Real planning inputs
+usually are not. They are PRD snippets, Jira notes, launch checklists, weekly
+status updates, CSV exports, and Slack summaries.
+
+Timeline Truth focuses on the handoff from messy planning material to a
+reviewable timeline:
+
+- preserve `source_refs` so every item can point back to evidence
+- flag missing dates, owners, and dependency problems instead of guessing
+- render portable Mermaid and Markdown artifacts
+- stay small enough to run inside local agent workflows
+
+## Why not just ask ChatGPT or Mermaid?
+
+ChatGPT can draft a timeline, and Mermaid can render one. Timeline Truth does a
+smaller job: it gives the agent a deterministic compiler/validator so the output
+keeps evidence, gaps, assumptions, and repeatable render formats.
+
+That matters when a TPM, PM, or engineering lead needs to review what is known,
+what is missing, and where each timeline item came from.
+
+## Install
+
+Local checkout:
+
+```bash
+npm install
+node src/mcp-server.js
+```
+
+Npm package config, after the npm package is published:
+
+```json
+{
+  "mcpServers": {
+    "timeline-truth": {
+      "command": "npx",
+      "args": ["-y", "--package=timeline-truth", "timeline-truth-mcp"]
+    }
+  }
+}
+```
+
+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).
+
+## MCP Tools
+
+- `create_timeline`: compile source content into timeline JSON plus Mermaid
+  outputs.
+- `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`.
+- `refine_timeline`: apply edits while preserving evidence (`source_refs`) and
+  assumptions.
+
+## Examples
+
+Realistic fixtures live in [examples](examples):
+
+- [PRD snippet](examples/prd-snippet.md)
+- [Jira CSV export](examples/jira-export.csv)
+- [Launch checklist](examples/launch-checklist.md)
+- [Status update](examples/status-update.md)
+
+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
+  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.
+- The server validates dependencies by item title, not by external issue keys.
+
+## Project Boundaries
+
+Timeline Truth is not a project management system, scheduling optimizer, or
+visual planning app. It is a compiler and validator for timeline artifacts.
+
+Good fits:
+
+- turning rough planning notes into a reviewable timeline
+- finding missing dates, owners, and dependency issues
+- generating Mermaid timelines for docs and status reports
+- preserving evidence during AI-assisted planning
+
+Poor fits:
+
+- capacity planning
+- drag-and-drop timeline editing
+- automatic schedule generation from vague goals
+- replacing Jira, Asana, Smartsheet, or similar systems of record
+
+## Development
+
+```bash
+npm install
+npm test
+npm run check
+npm pack --dry-run
+```
+
+See [docs/RELEASE.md](docs/RELEASE.md) before publishing.
+
+## Contributing
+
+Contributions are welcome when they keep the project narrow and evidence-first.
+Before adding features, check [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

package/docs/MCP-SETUP.md

@@ -0,0 +1,61 @@
+# MCP Setup
+
+Timeline Truth runs as a local stdio MCP server. It does not need network
+access, credentials, or hosted storage.
+
+## Local Checkout
+
+Use this while evaluating the repo or contributing changes:
+
+```json
+{
+  "mcpServers": {
+    "timeline-truth": {
+      "command": "node",
+      "args": ["C:/path/to/timeline-truth/src/mcp-server.js"]
+    }
+  }
+}
+```
+
+From the checkout, install dependencies once:
+
+```bash
+npm install
+```
+
+## Npm Package
+
+Use this after the `timeline-truth` npm package is published:
+
+```json
+{
+  "mcpServers": {
+    "timeline-truth": {
+      "command": "npx",
+      "args": ["-y", "--package=timeline-truth", "timeline-truth-mcp"]
+    }
+  }
+}
+```
+
+Before publish, `npx --package=timeline-truth timeline-truth-mcp` will fail
+because the package is not yet available from the public registry.
+
+## Agent Prompt
+
+Paste planning notes into your agent with this instruction:
+
+```text
+Use the timeline-truth MCP server. Call create_timeline with these notes as a
+single source. Then summarize the timeline, list gaps and assumptions, and show
+the mermaid_gantt output. Do not infer missing dates or owners; use the gaps
+from the tool as follow-up questions.
+```
+
+Useful follow-up calls:
+
+- `validate_timeline` after manual edits or agent refinements.
+- `render_timeline` when you need only Mermaid or Markdown output.
+- `refine_timeline` when a human answers a gap and you need to preserve
+  existing `source_refs`.

package/docs/RELEASE.md

@@ -0,0 +1,47 @@
+# Release Checklist
+
+Use this checklist before publishing a public version of `timeline-truth`.
+
+## 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.
+
+## Verify Local Quality
+
+```bash
+npm test
+npm run check
+npm pack --dry-run
+```
+
+Confirm the pack output includes:
+
+- `src/`
+- `docs/`
+- `examples/`
+- `README.md`
+- `LICENSE`
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+After publishing, rerun:
+
+```bash
+npm view timeline-truth version
+```
+
+Then test the documented MCP package command:
+
+```bash
+npx -y --package=timeline-truth timeline-truth-mcp
+```

package/examples/expected-output/jira-export.json

@@ -0,0 +1,23 @@
+{
+  "sourceId": "jira-export",
+  "itemTitles": [
+    "Discovery",
+    "Backend API",
+    "Beta milestone",
+    "Data migration"
+  ],
+  "gaps": [
+    {
+      "itemTitle": "Backend API",
+      "field": "end"
+    },
+    {
+      "itemTitle": "Data migration",
+      "field": "start"
+    },
+    {
+      "itemTitle": "Data migration",
+      "field": "end"
+    }
+  ]
+}

package/examples/expected-output/launch-checklist.json

@@ -0,0 +1,19 @@
+{
+  "sourceId": "launch-checklist",
+  "itemTitles": [
+    "Scope review",
+    "Production readiness",
+    "Legal approval",
+    "Go live"
+  ],
+  "gaps": [
+    {
+      "itemTitle": "Legal approval",
+      "field": "start"
+    },
+    {
+      "itemTitle": "Legal approval",
+      "field": "end"
+    }
+  ]
+}

package/examples/expected-output/prd-snippet.json

@@ -0,0 +1,19 @@
+{
+  "sourceId": "prd-snippet",
+  "itemTitles": [
+    "Discovery",
+    "API contract",
+    "Checkout QA",
+    "Launch decision"
+  ],
+  "gaps": [
+    {
+      "itemTitle": "Checkout QA",
+      "field": "start"
+    },
+    {
+      "itemTitle": "Checkout QA",
+      "field": "end"
+    }
+  ]
+}

package/examples/expected-output/status-update.json

@@ -0,0 +1,27 @@
+{
+  "sourceId": "status-update",
+  "itemTitles": [
+    "Mobile beta",
+    "Partner review",
+    "Rollout",
+    "Analytics setup"
+  ],
+  "gaps": [
+    {
+      "itemTitle": "Partner review",
+      "field": "owner"
+    },
+    {
+      "itemTitle": "Rollout",
+      "field": "start"
+    },
+    {
+      "itemTitle": "Rollout",
+      "field": "end"
+    },
+    {
+      "itemTitle": "Analytics setup",
+      "field": "owner"
+    }
+  ]
+}

package/examples/jira-export.csv

@@ -0,0 +1,5 @@
+title,type,start,end,owner,status,dependencies
+Discovery,task,2026-07-01,2026-07-03,PM,done,
+Backend API,task,2026-07-04,,BE,active,Discovery
+Beta milestone,milestone,2026-07-12,,PM,planned,Backend API
+Data migration,task,,,DBA,planned,Backend API

package/examples/launch-checklist.md

@@ -0,0 +1,6 @@
+# Launch Checklist
+
+- [x] Scope review: 2026-08-01 to 2026-08-02 owner TPM status done
+- [ ] Production readiness: starts 2026-08-05 duration 3d owner SRE status planned depends on Scope review
+- [ ] Legal approval owner Legal status planned depends on Scope review
+- [ ] Go live milestone on 2026-08-12 owner PM status planned depends on Production readiness, Legal approval

package/examples/prd-snippet.md

@@ -0,0 +1,6 @@
+# Payments Launch PRD Timeline
+
+Discovery: 2026-06-01 to 2026-06-05 owner PM status planned
+API contract: starts 2026-06-06 duration 4d owner Platform status planned depends on Discovery
+Checkout QA: owner QA status planned depends on API contract
+Launch decision milestone on 2026-06-17 owner PM status planned depends on Checkout QA

package/examples/status-update.md

@@ -0,0 +1,6 @@
+# Weekly Status
+
+Mobile beta: starts 2026-09-02 duration 5d owner Mobile status active
+Partner review milestone on 2026-09-09 status planned
+Rollout owner TPM status planned depends on Mobile beta, Partner review
+Analytics setup: 2026-09-03 to 2026-09-06 status planned

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "timeline-truth",
+  "version": "0.1.0",
+  "description": "Open-source MCP server for compiling messy project planning inputs into evidence-preserving timelines.",
+  "author": "hilmimuktitama",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hilmimuktitama/timeline-truth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hilmimuktitama/timeline-truth/issues"
+  },
+  "homepage": "https://github.com/hilmimuktitama/timeline-truth#readme",
+  "type": "module",
+  "bin": {
+    "timeline-truth-mcp": "src/mcp-server.js"
+  },
+  "files": [
+    "src",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "timeline",
+    "project-planning",
+    "mermaid",
+    "tpm",
+    "program-management"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node scripts/check-syntax.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/mcp-server.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+import { callTimelineTool, listTimelineTools } from "./mcp-tools.js";
+
+const server = new Server(
+  {
+    name: "timeline-truth",
+    version: "0.1.0"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: listTimelineTools()
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    return callTimelineTool(request.params.name, request.params.arguments ?? {});
+  } catch (error) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: error instanceof Error ? error.message : String(error)
+        }
+      ]
+    };
+  }
+});
+
+await server.connect(new StdioServerTransport());

package/src/mcp-tools.js

@@ -0,0 +1,136 @@
+import { createTimeline, refineTimeline, renderTimeline, validateTimeline } from "./timeline.js";
+
+const SOURCE_SCHEMA = {
+  type: "object",
+  required: ["content"],
+  additionalProperties: true,
+  properties: {
+    id: { type: "string", description: "Stable source identifier used 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.",
+      oneOf: [{ type: "string" }, { type: "object" }, { type: "array" }]
+    }
+  }
+};
+
+const TIMELINE_SCHEMA = {
+  type: "object",
+  required: ["items"],
+  additionalProperties: true,
+  properties: {
+    items: { type: "array", items: { type: "object", additionalProperties: true } },
+    milestones: { type: "array", items: { type: "object", additionalProperties: true } },
+    assumptions: { type: "array", items: { type: "string" } },
+    gaps: { type: "array", items: { type: "object", additionalProperties: true } },
+    render: { type: "object", additionalProperties: true }
+  }
+};
+
+export function listTimelineTools() {
+  return [
+    {
+      name: "create_timeline",
+      description:
+        "Compile pasted project planning text, Markdown, CSV, or JSON into a normalized timeline with gaps, assumptions, and Mermaid renders.",
+      inputSchema: {
+        type: "object",
+        required: ["sources"],
+        additionalProperties: false,
+        properties: {
+          sources: {
+            type: "array",
+            minItems: 1,
+            items: SOURCE_SCHEMA
+          }
+        }
+      }
+    },
+    {
+      name: "validate_timeline",
+      description:
+        "Validate a normalized timeline for missing dates, missing owners, unknown dependencies, circular dependencies, and impossible sequencing.",
+      inputSchema: {
+        type: "object",
+        required: ["timeline"],
+        additionalProperties: false,
+        properties: {
+          timeline: TIMELINE_SCHEMA
+        }
+      }
+    },
+    {
+      name: "render_timeline",
+      description: "Render a normalized timeline as Mermaid Gantt, Mermaid timeline, or compact Markdown.",
+      inputSchema: {
+        type: "object",
+        required: ["timeline"],
+        additionalProperties: false,
+        properties: {
+          timeline: TIMELINE_SCHEMA,
+          format: {
+            type: "string",
+            enum: ["mermaid_gantt", "mermaid_timeline", "markdown"],
+            default: "mermaid_gantt"
+          }
+        }
+      }
+    },
+    {
+      name: "refine_timeline",
+      description:
+        "Apply agent/user edits to an existing timeline while preserving source_refs and assumptions unless explicitly replaced.",
+      inputSchema: {
+        type: "object",
+        required: ["timeline", "updates"],
+        additionalProperties: false,
+        properties: {
+          timeline: TIMELINE_SCHEMA,
+          updates: {
+            type: "array",
+            items: {
+              type: "object",
+              required: ["set"],
+              additionalProperties: false,
+              properties: {
+                matchTitle: { type: "string" },
+                matchId: { type: "string" },
+                set: { type: "object", additionalProperties: true }
+              }
+            }
+          }
+        }
+      }
+    }
+  ];
+}
+
+export function callTimelineTool(name, args = {}) {
+  switch (name) {
+    case "create_timeline":
+      return jsonContent(createTimeline({ sources: args.sources }));
+    case "validate_timeline":
+      return jsonContent(validateTimeline(args.timeline));
+    case "render_timeline":
+      return textContent(renderTimeline(args.timeline, { format: args.format }));
+    case "refine_timeline":
+      return jsonContent(refineTimeline(args.timeline, { updates: args.updates }));
+    default:
+      throw new Error(`Unknown timeline tool: ${name}`);
+  }
+}
+
+function jsonContent(value) {
+  return textContent(JSON.stringify(value, null, 2));
+}
+
+function textContent(text) {
+  return {
+    content: [
+      {
+        type: "text",
+        text
+      }
+    ]
+  };
+}

package/src/timeline.js

@@ -0,0 +1,512 @@
+const DATE_PATTERN = /\b\d{4}-\d{2}-\d{2}\b/g;
+
+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 timeline = normalizeTimeline({
+    items,
+    assumptions: [
+      ...importedAssumptions,
+      "No dates were inferred. Missing dates are reported as gaps for agent or user follow-up."
+    ],
+    gaps: [],
+    render: {
+      audience: "TPM/PM",
+      defaultFormats: ["mermaid_gantt", "mermaid_timeline", "markdown"]
+    }
+  });
+  const validation = validateTimeline(timeline);
+  const validatedTimeline = {
+    ...timeline,
+    gaps: validation.gaps,
+    issues: validation.issues
+  };
+
+  return {
+    timeline: validatedTimeline,
+    assumptions: validatedTimeline.assumptions,
+    gaps: validatedTimeline.gaps,
+    issues: validation.issues,
+    renders: {
+      mermaid_gantt: renderTimeline(validatedTimeline, { format: "mermaid_gantt" }),
+      mermaid_timeline: renderTimeline(validatedTimeline, { format: "mermaid_timeline" }),
+      markdown: renderTimeline(validatedTimeline, { format: "markdown" })
+    }
+  };
+}
+
+export function validateTimeline(timeline = {}) {
+  const normalized = normalizeTimeline(timeline);
+  const gaps = [];
+  const issues = [];
+
+  for (const item of normalized.items) {
+    if (!item.start) {
+      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") {
+      gaps.push(makeGap(item, "end", "Missing end date or duration for a non-milestone item."));
+    }
+
+    if (!item.owner) {
+      gaps.push(makeGap(item, "owner", "Missing accountable owner."));
+    }
+
+    if (item.type === "milestone" && !item.owner) {
+      gaps.push(makeGap(item, "owner", "Milestone ownership is ambiguous."));
+    }
+  }
+
+  for (const item of normalized.items) {
+    for (const dependency of item.dependencies) {
+      if (!normalized.items.some((candidate) => candidate.title === dependency)) {
+        issues.push({
+          type: "unknown_dependency",
+          severity: "warning",
+          itemTitle: item.title,
+          dependency,
+          message: `Dependency "${dependency}" was not found in the timeline.`
+        });
+      }
+    }
+  }
+
+  const cycles = findDependencyCycles(normalized.items);
+  for (const cycle of cycles) {
+    issues.push({
+      type: "circular_dependency",
+      severity: "error",
+      items: cycle,
+      message: `Circular dependency detected: ${cycle.join(" -> ")}.`
+    });
+  }
+
+  for (const item of normalized.items) {
+    for (const dependencyTitle of item.dependencies) {
+      const dependency = normalized.items.find((candidate) => candidate.title === dependencyTitle);
+      if (dependency?.end && item.start && item.start < dependency.end) {
+        issues.push({
+          type: "impossible_sequence",
+          severity: "warning",
+          itemTitle: item.title,
+          dependency: dependencyTitle,
+          message: `"${item.title}" starts before dependency "${dependencyTitle}" ends.`
+        });
+      }
+    }
+  }
+
+  return { gaps, issues };
+}
+
+export function renderTimeline(timeline = {}, options = {}) {
+  const normalized = normalizeTimeline(timeline);
+  const format = options.format ?? "mermaid_gantt";
+
+  if (format === "mermaid_timeline") {
+    return renderMermaidTimeline(normalized);
+  }
+
+  if (format === "markdown") {
+    return renderMarkdown(normalized);
+  }
+
+  return renderMermaidGantt(normalized);
+}
+
+export function refineTimeline(timeline = {}, refinement = {}) {
+  const refined = normalizeTimeline(structuredCloneSafe(timeline));
+  const updates = Array.isArray(refinement.updates) ? refinement.updates : [];
+
+  for (const update of updates) {
+    const item = refined.items.find((candidate) => {
+      if (update.matchTitle) return candidate.title === update.matchTitle;
+      if (update.matchId) return candidate.id === update.matchId;
+      return false;
+    });
+
+    if (!item || !update.set || typeof update.set !== "object") continue;
+
+    const preservedSourceRefs = item.source_refs;
+    const mergedItem = { ...item, ...update.set };
+    Object.assign(item, normalizeItem(mergedItem, update.set.source_refs ?? preservedSourceRefs));
+  }
+
+  const validation = validateTimeline(refined);
+  return {
+    ...normalizeTimeline(refined),
+    gaps: validation.gaps,
+    issues: validation.issues
+  };
+}
+
+function parseSource(source, index, importedAssumptions) {
+  const normalizedSource = {
+    id: source?.id || `source-${index + 1}`,
+    type: source?.type || "text",
+    content: source?.content ?? ""
+  };
+
+  if (normalizedSource.type === "json") {
+    return parseJsonSource(normalizedSource, importedAssumptions);
+  }
+
+  if (normalizedSource.type === "csv") {
+    return parseCsvSource(normalizedSource);
+  }
+
+  return parseTextSource(normalizedSource);
+}
+
+function parseJsonSource(source, importedAssumptions) {
+  const parsed = typeof source.content === "string" ? JSON.parse(source.content) : source.content;
+  const rawItems = Array.isArray(parsed) ? parsed : parsed.items ?? [];
+
+  if (Array.isArray(parsed.assumptions)) {
+    importedAssumptions.push(...parsed.assumptions.filter((assumption) => typeof assumption === "string"));
+  }
+
+  return rawItems.map((item, index) =>
+    normalizeItem(item, item.source_refs ?? [{ sourceId: source.id, line: index + 1 }])
+  );
+}
+
+function parseCsvSource(source) {
+  const rows = parseCsv(source.content);
+  if (rows.length === 0) return [];
+
+  const headers = rows[0].map((header) => normalizeHeader(header));
+  return rows.slice(1).flatMap((row, index) => {
+    if (row.every((cell) => cell.trim() === "")) return [];
+
+    const record = {};
+    headers.forEach((header, headerIndex) => {
+      record[header] = row[headerIndex] ?? "";
+    });
+
+    return normalizeItem(csvRecordToItem(record), [{ sourceId: source.id, line: index + 2 }]);
+  });
+}
+
+function parseTextSource(source) {
+  return String(source.content)
+    .split(/\r?\n/)
+    .map((line, index) => parseTextLine(line, source.id, index + 1))
+    .filter(Boolean);
+}
+
+function parseTextLine(line, sourceId, lineNumber) {
+  const trimmed = normalizePlanningLine(line);
+  if (!trimmed) return null;
+
+  const dates = [...trimmed.matchAll(DATE_PATTERN)].map((match) => match[0]);
+  const lower = trimmed.toLowerCase();
+  const type = lower.includes("milestone") ? "milestone" : "task";
+  const title = extractTitle(trimmed, type);
+  const owner = extractKeywordValue(trimmed, "owner");
+  const status = extractKeywordValue(trimmed, "status") || "planned";
+  const dependencies = extractDependencies(trimmed);
+  const duration = extractDuration(trimmed);
+  const item = {
+    title,
+    type,
+    start: dates[0],
+    end: dates[1],
+    duration,
+    owner,
+    status,
+    dependencies,
+    confidence: dates.length > 0 ? 0.75 : 0.45
+  };
+
+  return normalizeItem(item, [{ sourceId, line: lineNumber, text: trimmed }]);
+}
+
+function normalizePlanningLine(line) {
+  const trimmed = String(line).trim();
+  if (/^#{1,6}\s+/.test(trimmed)) return "";
+
+  return trimmed
+    .replace(/^[-*]\s+\[[ xX]\]\s+/, "")
+    .replace(/^[-*]\s+/, "");
+}
+
+function extractTitle(line, type) {
+  const colonIndex = line.indexOf(":");
+  if (colonIndex > 0) return cleanTitle(line.slice(0, colonIndex));
+
+  const milestoneMatch = line.match(/^(.+?)\s+milestone\b/i);
+  if (milestoneMatch) return cleanTitle(milestoneMatch[1]);
+
+  const dateMatch = line.match(DATE_PATTERN);
+  if (dateMatch?.index && dateMatch.index > 0) return cleanTitle(line.slice(0, dateMatch.index));
+
+  const ownerIndex = line.search(/\sowner\b/i);
+  if (ownerIndex > 0) return cleanTitle(line.slice(0, ownerIndex));
+
+  return cleanTitle(type === "milestone" ? line.replace(/\bmilestone\b/gi, "") : line);
+}
+
+function cleanTitle(title) {
+  return title
+    .replace(/\b(starts?|start|from|on|by|duration|depends on|owner|status)\b.*$/i, "")
+    .trim()
+    .replace(/[.:-]+$/g, "")
+    .trim();
+}
+
+function extractKeywordValue(line, keyword) {
+  const pattern = new RegExp(`\\b${keyword}\\s+([^,;]+?)(?=\\s+(?:status|owner|depends? on|duration|starts?|from|on)\\b|$)`, "i");
+  const match = line.match(pattern);
+  return match ? match[1].trim() : undefined;
+}
+
+function extractDependencies(line) {
+  const match = line.match(/\bdepends? on\s+(.+?)(?=\s+(?:owner|status|duration|starts?|from|on)\b|$)/i);
+  if (!match) return [];
+
+  return match[1]
+    .split(/[|,;]/)
+    .map((dependency) => dependency.trim())
+    .filter(Boolean);
+}
+
+function extractDuration(line) {
+  const match = line.match(/\bduration\s+(\d+\s*[dwmy])\b/i);
+  return match ? match[1].replace(/\s+/g, "") : undefined;
+}
+
+function csvRecordToItem(record) {
+  return {
+    title: record.title || record.name || record.task || record.milestone,
+    type: record.type,
+    start: record.start || record.start_date,
+    end: record.end || record.end_date,
+    duration: record.duration,
+    owner: record.owner || record.assignee,
+    status: record.status,
+    dependencies: record.dependencies || record.depends_on,
+    confidence: record.confidence ? Number(record.confidence) : undefined
+  };
+}
+
+function normalizeTimeline(timeline = {}) {
+  const items = Array.isArray(timeline.items)
+    ? timeline.items.map((item) => normalizeItem(item, item.source_refs))
+    : [];
+  const milestones = items.filter((item) => item.type === "milestone");
+
+  return {
+    items,
+    milestones,
+    assumptions: Array.isArray(timeline.assumptions) ? [...timeline.assumptions] : [],
+    gaps: Array.isArray(timeline.gaps) ? [...timeline.gaps] : [],
+    render: timeline.render && typeof timeline.render === "object" ? { ...timeline.render } : {}
+  };
+}
+
+function normalizeItem(item = {}, sourceRefs = []) {
+  const dependencies = Array.isArray(item.dependencies)
+    ? item.dependencies
+    : typeof item.dependencies === "string"
+      ? item.dependencies.split(/[|,;]/)
+      : [];
+
+  return {
+    id: item.id || slugify(item.title || "untitled"),
+    title: String(item.title || "Untitled").trim(),
+    type: item.type === "milestone" ? "milestone" : "task",
+    start: blankToUndefined(item.start),
+    end: blankToUndefined(item.end),
+    duration: blankToUndefined(item.duration),
+    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,
+    source_refs: normalizeSourceRefs(sourceRefs)
+  };
+}
+
+function normalizeSourceRefs(sourceRefs) {
+  return Array.isArray(sourceRefs)
+    ? sourceRefs.map((sourceRef) => ({ ...sourceRef }))
+    : [];
+}
+
+function makeGap(item, field, question) {
+  return {
+    itemTitle: item.title,
+    field,
+    question,
+    source_refs: item.source_refs
+  };
+}
+
+function findDependencyCycles(items) {
+  const byTitle = new Map(items.map((item) => [item.title, item]));
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+  const cycles = [];
+
+  function visit(title) {
+    if (visiting.has(title)) {
+      const cycleStart = stack.indexOf(title);
+      cycles.push([...stack.slice(cycleStart), title]);
+      return;
+    }
+
+    if (visited.has(title)) return;
+
+    const item = byTitle.get(title);
+    if (!item) return;
+
+    visiting.add(title);
+    stack.push(title);
+
+    for (const dependency of item.dependencies) {
+      visit(dependency);
+    }
+
+    stack.pop();
+    visiting.delete(title);
+    visited.add(title);
+  }
+
+  for (const item of items) {
+    visit(item.title);
+  }
+
+  return dedupeCycles(cycles);
+}
+
+function dedupeCycles(cycles) {
+  const seen = new Set();
+  return cycles.filter((cycle) => {
+    const key = [...new Set(cycle)].sort().join("|");
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function renderMermaidGantt(timeline) {
+  const lines = ["gantt", "  title Project Timeline", "  dateFormat YYYY-MM-DD", "  axisFormat %b %d", "  section Plan"];
+
+  for (const item of timeline.items) {
+    const label = escapeMermaidText(`${item.title}${item.owner ? ` (${item.owner})` : ""}`);
+    if (item.type === "milestone" && item.start) {
+      lines.push(`  ${label} :milestone, ${item.start}, 0d`);
+    } else if (item.start && item.end) {
+      lines.push(`  ${label} :${item.status || "unknown"}, ${item.start}, ${item.end}`);
+    } else if (item.start && item.duration) {
+      lines.push(`  ${label} :${item.status || "unknown"}, ${item.start}, ${item.duration}`);
+    } else {
+      lines.push(`  %% ${label} omitted from chart: missing defensible date or duration`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function renderMermaidTimeline(timeline) {
+  const lines = ["timeline", "  title Project Timeline"];
+
+  for (const item of timeline.items) {
+    if (!item.start) {
+      lines.push(`  ${escapeMermaidText("Unscheduled")} : ${escapeMermaidText(item.title)}`);
+      continue;
+    }
+
+    lines.push(`  ${item.start} : ${escapeMermaidText(item.title)}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function renderMarkdown(timeline) {
+  const lines = ["## Timeline", ""];
+
+  for (const item of timeline.items) {
+    const window = item.start ? `${item.start}${item.end ? ` to ${item.end}` : item.duration ? ` for ${item.duration}` : ""}` : "date needed";
+    lines.push(`- **${item.title}** (${item.type}, ${item.status}) - ${window}${item.owner ? ` - owner: ${item.owner}` : ""}`);
+  }
+
+  if (timeline.gaps.length > 0) {
+    lines.push("", "## Gaps");
+    for (const gap of timeline.gaps) {
+      lines.push(`- ${gap.itemTitle}: ${gap.field} - ${gap.question}`);
+    }
+  }
+
+  if (timeline.assumptions.length > 0) {
+    lines.push("", "## Assumptions");
+    for (const assumption of timeline.assumptions) {
+      lines.push(`- ${assumption}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function parseCsv(content) {
+  const rows = [];
+  let row = [];
+  let cell = "";
+  let inQuotes = false;
+
+  for (let index = 0; index < String(content).length; index += 1) {
+    const character = String(content)[index];
+    const next = String(content)[index + 1];
+
+    if (character === '"' && inQuotes && next === '"') {
+      cell += '"';
+      index += 1;
+    } else if (character === '"') {
+      inQuotes = !inQuotes;
+    } else if (character === "," && !inQuotes) {
+      row.push(cell.trim());
+      cell = "";
+    } else if ((character === "\n" || character === "\r") && !inQuotes) {
+      if (character === "\r" && next === "\n") index += 1;
+      row.push(cell.trim());
+      rows.push(row);
+      row = [];
+      cell = "";
+    } else {
+      cell += character;
+    }
+  }
+
+  row.push(cell.trim());
+  rows.push(row);
+  return rows.filter((cells) => cells.some((value) => value !== ""));
+}
+
+function normalizeHeader(header) {
+  return String(header).trim().toLowerCase().replace(/[\s-]+/g, "_");
+}
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function blankToUndefined(value) {
+  if (value === undefined || value === null) return undefined;
+  const normalized = String(value).trim();
+  return normalized === "" ? undefined : normalized;
+}
+
+function escapeMermaidText(value) {
+  return String(value).replace(/[:#;]/g, "-").trim();
+}
+
+function structuredCloneSafe(value) {
+  return JSON.parse(JSON.stringify(value));
+}