Merge branch '002-direct-db-access': Direct database access for scripts (v0.2.0)

docs: update CLAUDE.md and bump version to 0.2.0
- Add persistent SQLite database to active technologies - Update recent changes section for 002-direct-db-access - Bump package version to 0.2.0 in uv.lock
2026-01-08 13:02:07 -05:00 · 2026-01-08 13:01:49 -05:00 · 2026-01-08 12:56:29 -05:00 · 2026-01-08 12:54:56 -05:00 · 2026-01-08 12:38:42 -05:00 · 2026-01-08 12:22:53 -05:00
35 changed files with 3209 additions and 246 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -38,9 +38,12 @@ htmlcov/
 .tox/
 .nox/

-# XER files (may contain sensitive project data)
-*.xer
+# Schedule files
+schedules/

 # OS
 .DS_Store
 Thumbs.db
+
+
+.claude/skills/
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,6 +4,9 @@ Auto-generated from all feature plans. Last updated: 2026-01-06

 ## Active Technologies
 - SQLite in-memory database (001-schedule-tools)
+- Python 3.14 + mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib) (001-schedule-tools)
+- In-memory SQLite database (populated from XER files at runtime) (001-schedule-tools)
+- SQLite database file (persistent) in addition to existing in-memory option (002-direct-db-access)

 - Python 3.14 + mcp (MCP SDK), sqlite3 (stdlib) (001-schedule-tools)

@@ -23,9 +26,10 @@ cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLO
 Python 3.14: Follow standard conventions

 ## Recent Changes
+- 002-direct-db-access: Added Python 3.14 + mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib)
+- 001-schedule-tools: Added Python 3.14 + mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib)
 - 001-schedule-tools: Added Python 3.14 + mcp (MCP SDK), sqlite3 (stdlib)

- 001-schedule-tools: Added Python 3.14 + mcp (MCP SDK), sqlite3 (stdlib)

 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "xer-mcp"
-version = "0.1.0"
+version = "0.2.0"
 description = "MCP server for querying Primavera P6 XER schedule data"
 readme = "README.md"
 requires-python = ">=3.14"
--- a/specs/001-schedule-tools/contracts/mcp-tools.json
+++ b/specs/001-schedule-tools/contracts/mcp-tools.json
@@ -301,7 +301,8 @@
        "target_start_date": { "type": "string", "format": "date-time" },
        "target_end_date": { "type": "string", "format": "date-time" },
        "status_code": { "type": "string" },
-        "driving_path_flag": { "type": "boolean" }
+        "driving_path_flag": { "type": "boolean" },
+        "milestone_type": { "type": "string", "enum": ["start", "finish", null], "description": "Type of milestone: 'start' for start milestones, 'finish' for finish milestones, null for non-milestones" }
      }
    },
    "ActivityDetail": {
--- a/specs/001-schedule-tools/data-model.md
+++ b/specs/001-schedule-tools/data-model.md
@@ -54,6 +54,7 @@ A unit of work in the schedule.
 | task_code | string | Yes | User-visible activity code |
 | task_name | string | Yes | Activity description |
 | task_type | enum | Yes | TT_Task, TT_Mile, TT_LOE, TT_WBS, TT_Rsrc |
+| milestone_type | enum | No | 'start' for start milestones, 'finish' for finish milestones, null for non-milestones |
 | target_start_date | datetime | No | Planned start |
 | target_end_date | datetime | No | Planned finish |
 | early_start_date | datetime | No | Calculated early start (for driving computation) |
--- a/specs/001-schedule-tools/plan.md
+++ b/specs/001-schedule-tools/plan.md
@@ -1,47 +1,38 @@
-# Implementation Plan: Add Driving Flag to Relationships
+# Implementation Plan: Project Schedule Tools

-**Branch**: `001-schedule-tools` | **Date**: 2026-01-06 | **Spec**: [spec.md](./spec.md)
+**Branch**: `001-schedule-tools` | **Date**: 2026-01-08 | **Spec**: [spec.md](./spec.md)
 **Input**: Feature specification from `/specs/001-schedule-tools/spec.md`

 ## Summary

-Extend the existing XER MCP Server implementation to include the "driving" flag in all relationship query responses. This requires updating the database schema, XER parser, and query functions to extract and return the driving relationship indicator from Primavera P6 schedule data.
+Build an MCP server that provides 9 tools for querying Primavera P6 XER schedule data. The server parses XER files into an in-memory SQLite database and exposes tools for loading files, querying activities, relationships, milestones, critical path, and project summary. Uses Python 3.14 with the MCP SDK and follows TDD practices per the project constitution.

 ## Technical Context

 **Language/Version**: Python 3.14
-**Primary Dependencies**: mcp (MCP SDK), sqlite3 (stdlib)
-**Storage**: SQLite in-memory database
-**Testing**: pytest, pytest-asyncio
-**Target Platform**: Linux server (local MCP server)
-**Project Type**: single
-**Performance Goals**: Query response < 1 second, load < 5 seconds for 10k activities
-**Constraints**: Single-user operation, in-memory storage for loaded XER data
-**Scale/Scope**: Files up to 50,000 activities
+**Primary Dependencies**: mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib)
+**Storage**: In-memory SQLite database (populated from XER files at runtime)
+**Testing**: pytest>=8.0.0, pytest-asyncio>=0.24.0
+**Target Platform**: Local server (Linux/macOS/Windows with file system access)
+**Project Type**: Single project
+**Performance Goals**: Load + query XER files ≤5 seconds for 10,000 activities; query response <1 second
+**Constraints**: Memory sufficient for 50,000 activities; single-user operation
+**Scale/Scope**: MCP server with 9 tools; handles typical P6 project files (up to 50,000 activities)

 ## Constitution Check

 *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

-| Principle | Status | Evidence/Notes |
-|-----------|--------|----------------|
-| I. Test-First Development | ✅ PASS | TDD required - write failing tests first for driving flag in relationship responses |
-| II. Extensibility Architecture | ✅ PASS | Current design already separates parser → db → query → tool layers |
-| III. MCP Protocol Compliance | ✅ PASS | Tool schemas already JSON Schema compliant; no schema changes needed |
-| IV. XER Format Fidelity | ✅ PASS | Must parse `driving_flag` from TASKPRED table in XER files |
-| V. Semantic Versioning | ✅ PASS | Adding new field to response is backward-compatible (MINOR) |
+| Principle | Requirement | Status | Notes |
+|-----------|-------------|--------|-------|
+| **I. Test-First Development** | TDD mandatory; tests fail before implementation | ✅ PASS | Contract tests for all 9 MCP tools; integration tests for XER parsing |
+| **II. Extensibility Architecture** | Core parsing separate from MCP transport; pluggable handlers | ✅ PASS | Table handlers are pluggable (`parser/table_handlers/`); tools are modular (`tools/`) |
+| **III. MCP Protocol Compliance** | Complete JSON schemas; MCP error format; compliant transport | ✅ PASS | Using official MCP SDK; tool definitions include JSON schemas |
+| **IV. XER Format Fidelity** | No data loss; preserve precision; handle all standard tables | ✅ PASS | Parsing TASK, TASKPRED, PROJECT, PROJWBS, CALENDAR; dates preserve precision |
+| **V. Semantic Versioning** | SemVer for releases; breaking changes documented | ✅ PASS | Version 0.1.0; initial development phase |
+| **Technical Standards** | Python 3.14; type hints; ruff formatting | ✅ PASS | pyproject.toml configured for Python 3.14, ruff, pytest |

-**Pre-design Status**: All gates PASS
-
-**Post-design Status** (re-evaluated after Phase 1):
-
-| Principle | Status | Evidence/Notes |
-|-----------|--------|----------------|
-| I. Test-First Development | ✅ PASS | Tests will verify: (1) early dates parsed from TASK, (2) driving computed correctly, (3) driving included in all relationship responses |
-| II. Extensibility Architecture | ✅ PASS | Driving computation is isolated in query layer; no changes to parser or model structure |
-| III. MCP Protocol Compliance | ✅ PASS | Response schema updated in contracts/mcp-tools.json |
-| IV. XER Format Fidelity | ✅ PASS | Research confirmed: driving is computed from schedule dates (matching P6 behavior), not stored in XER |
-| V. Semantic Versioning | ✅ PASS | Adding `driving` field is backward-compatible (MINOR version bump)
+**Gate Result**: PASS - All constitution principles satisfied. Proceed to Phase 0.

 ## Project Structure

@@ -49,53 +40,116 @@ Extend the existing XER MCP Server implementation to include the "driving" flag

 ```text
 specs/001-schedule-tools/
-├── plan.md              # This file
-├── research.md          # Phase 0 output
-├── data-model.md        # Phase 1 output
-├── quickstart.md        # Phase 1 output
-├── contracts/           # Phase 1 output
-└── tasks.md             # Phase 2 output (/speckit.tasks)
+├── spec.md              # Feature specification
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
 ```

 ### Source Code (repository root)

 ```text
-src/
-├── xer_mcp/
-│   ├── models/
-│   │   └── relationship.py   # Add driving field to dataclass
-│   ├── parser/
-│   │   └── table_handlers/
-│   │       └── taskpred.py   # Parse driving_flag from XER
-│   ├── db/
-│   │   ├── schema.py         # Add driving column to relationships table
-│   │   ├── loader.py         # Store driving flag when loading
-│   │   └── queries.py        # Return driving in relationship queries
-│   └── tools/
-│       ├── list_relationships.py  # Response already uses query result
-│       ├── get_predecessors.py    # Response already uses query result
-│       └── get_successors.py      # Response already uses query result
+src/xer_mcp/
+├── __init__.py
+├── __main__.py              # Entry point
+├── server.py                # MCP server setup and tool registration
+├── errors.py                # Error types
+├── models/                  # Data models (dataclasses)
+│   ├── __init__.py
+│   ├── project.py
+│   ├── activity.py
+│   ├── relationship.py
+│   ├── wbs.py
+│   ├── calendar.py
+│   └── pagination.py
+├── parser/                  # XER file parsing
+│   ├── __init__.py
+│   ├── xer_parser.py        # Main parser
+│   └── table_handlers/      # Pluggable table handlers
+│       ├── __init__.py
+│       ├── base.py
+│       ├── project.py
+│       ├── task.py
+│       ├── taskpred.py
+│       ├── projwbs.py
+│       └── calendar.py
+├── db/                      # SQLite database layer
+│   ├── __init__.py
+│   ├── schema.py            # Table definitions
+│   ├── loader.py            # Data loading
+│   └── queries.py           # Query functions
+└── tools/                   # MCP tool implementations
+    ├── __init__.py
+    ├── load_xer.py
+    ├── list_activities.py
+    ├── get_activity.py
+    ├── list_relationships.py
+    ├── get_predecessors.py
+    ├── get_successors.py
+    ├── get_project_summary.py
+    ├── list_milestones.py
+    └── get_critical_path.py

 tests/
-├── contract/
-│   ├── test_list_relationships.py  # Verify driving flag in response
-│   ├── test_get_predecessors.py    # Verify driving flag in response
-│   └── test_get_successors.py      # Verify driving flag in response
-├── integration/
-│   └── test_xer_parsing.py         # Verify driving flag parsed from XER
-└── unit/
-    ├── test_table_handlers.py      # Test TASKPRED handler parses driving
-    └── test_db_queries.py          # Test queries return driving flag
+├── __init__.py
+├── conftest.py              # Shared fixtures
+├── contract/                # MCP tool contract tests
+│   ├── __init__.py
+│   ├── test_load_xer.py
+│   ├── test_list_activities.py
+│   ├── test_get_activity.py
+│   ├── test_list_relationships.py
+│   ├── test_get_predecessors.py
+│   ├── test_get_successors.py
+│   ├── test_get_project_summary.py
+│   ├── test_list_milestones.py
+│   └── test_get_critical_path.py
+├── integration/             # XER parsing integration tests
+│   ├── __init__.py
+│   └── test_xer_parsing.py
+└── unit/                    # Unit tests
+    ├── __init__.py
+    ├── test_parser.py
+    ├── test_table_handlers.py
+    └── test_db_queries.py
 ```

-**Structure Decision**: Single project structure (existing). No new directories needed.
+**Structure Decision**: Single project structure with domain-specific organization: `models/` for data structures, `parser/` for XER file handling with pluggable table handlers, `db/` for SQLite storage layer, and `tools/` for MCP tool implementations. Tests follow contract/integration/unit hierarchy per constitution requirements.

 ## Complexity Tracking

-> No constitution violations. Implementation is a focused enhancement to existing architecture.
+> **Fill ONLY if Constitution Check has violations that must be justified**

-| Item | Assessment |
-|------|------------|
-| Scope | Small - single field addition across 4 layers |
-| Risk | Low - additive change, no behavior modification |
-| Testing | Contract tests + unit tests for each layer |
+No violations. All constitution principles satisfied.
+
+## Post-Design Constitution Re-Check
+
+*Re-evaluation after Phase 1 design artifacts are complete.*
+
+| Principle | Status | Verification |
+|-----------|--------|--------------|
+| **I. Test-First Development** | ✅ PASS | Contract tests defined in `tests/contract/` for all 9 tools; integration tests in `tests/integration/` |
+| **II. Extensibility Architecture** | ✅ PASS | Table handlers pluggable via registry pattern; tools are modular functions; schema separates concerns |
+| **III. MCP Protocol Compliance** | ✅ PASS | `contracts/mcp-tools.json` defines complete JSON schemas for all tools with input/output schemas |
+| **IV. XER Format Fidelity** | ✅ PASS | Data model preserves all date precision; handles all 5 standard tables; driving flag computed accurately |
+| **V. Semantic Versioning** | ✅ PASS | Version 0.1.0 in contract schema; following SemVer |
+| **Technical Standards** | ✅ PASS | Type hints throughout models; ruff configured; pytest async mode enabled |
+
+**Post-Design Gate Result**: PASS - Design artifacts align with constitution. Ready for task generation.
+
+## Generated Artifacts
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| Research | `specs/001-schedule-tools/research.md` | Technology decisions, XER format analysis, driving flag computation |
+| Data Model | `specs/001-schedule-tools/data-model.md` | Entity definitions, SQLite schema, validation rules |
+| Contracts | `specs/001-schedule-tools/contracts/mcp-tools.json` | MCP tool JSON schemas (input/output) |
+| Quickstart | `specs/001-schedule-tools/quickstart.md` | Usage guide with examples |
+| Agent Context | `CLAUDE.md` | Updated with Python 3.14, MCP SDK, SQLite |
+
+## Next Steps
+
+Run `/speckit.tasks` to generate implementation tasks from this plan.
--- a/specs/001-schedule-tools/quickstart.md
+++ b/specs/001-schedule-tools/quickstart.md
@@ -226,6 +226,34 @@ Use the get_critical_path tool
 Use the list_milestones tool
 ```

+**Response**:
+```json
+{
+  "milestones": [
+    {
+      "task_id": "M001",
+      "task_code": "MS-START",
+      "task_name": "Project Start",
+      "target_start_date": "2026-01-15T08:00:00",
+      "target_end_date": "2026-01-15T08:00:00",
+      "status_code": "TK_Complete",
+      "milestone_type": "start"
+    },
+    {
+      "task_id": "M025",
+      "task_code": "MS-END",
+      "task_name": "Project Complete",
+      "target_start_date": "2026-06-30T17:00:00",
+      "target_end_date": "2026-06-30T17:00:00",
+      "status_code": "TK_NotStart",
+      "milestone_type": "finish"
+    }
+  ]
+}
+```
+
+The `milestone_type` field indicates whether the milestone is a Start Milestone (`"start"`) or a Finish Milestone (`"finish"`).
+
 ## Pagination

 All list operations support pagination:
--- a/specs/001-schedule-tools/spec.md
+++ b/specs/001-schedule-tools/spec.md
@@ -75,7 +75,7 @@ As an AI assistant user, I want to get a high-level summary of the project sched
 **Acceptance Scenarios**:

 1. **Given** an XER file is loaded, **When** I request the project summary, **Then** I receive project name, data date, start date, finish date, and total activity count
-2. **Given** an XER file with milestones, **When** I request milestones, **Then** I receive a list of milestone activities with their target dates
+2. **Given** an XER file with milestones, **When** I request milestones, **Then** I receive a list of all milestone activities (both Start Milestones and Finish Milestones) with their target dates and milestone type
 3. **Given** an XER file is loaded, **When** I request the critical path, **Then** I receive the sequence of activities that determine the project end date
 4. **Given** no XER file is loaded, **When** I request project summary, milestones, or critical path, **Then** I receive a clear error message indicating no file is loaded

@@ -99,7 +99,7 @@ As an AI assistant user, I want to get a high-level summary of the project sched
 - **FR-004**: System MUST expose an MCP tool to retrieve detailed information for a specific activity by ID
 - **FR-005**: System MUST expose an MCP tool to query predecessor and successor relationships for any activity, including relationship type, lag value, and driving flag
 - **FR-006**: System MUST expose an MCP tool to retrieve project summary information (name, data date, plan dates, activity count)
- **FR-007**: System MUST expose an MCP tool to list milestone activities
+- **FR-007**: System MUST expose an MCP tool to list milestone activities, including both Start Milestones (TT_Mile with task_type='TT_Mile' and milestone_type='start') and Finish Milestones (task_type='TT_Mile' and milestone_type='finish')
 - **FR-008**: System MUST expose an MCP tool to identify the critical path
 - **FR-009**: System MUST return structured data that AI assistants can process and present to users
 - **FR-010**: System MUST provide clear, actionable error messages when operations fail
@@ -112,7 +112,7 @@ As an AI assistant user, I want to get a high-level summary of the project sched
 ### Key Entities

 - **Project**: The top-level container representing a P6 project with name, ID, start/finish dates, and calendar assignments
- **Activity**: A unit of work with ID, name, type (task/milestone/LOE), planned dates, actual dates, duration, and status
+- **Activity**: A unit of work with ID, name, type (task/milestone/LOE), milestone_type (start/finish for milestones, null otherwise), planned dates, actual dates, duration, and status
 - **Relationship**: A dependency link between two activities with type (FS/SS/FF/SF), lag value, and driving flag
 - **WBS (Work Breakdown Structure)**: Hierarchical organization of activities with ID, name, parent reference, and level
 - **Calendar**: Work schedule definition that determines working days and hours for activities (internal use only; not exposed as queryable entity)
@@ -141,6 +141,7 @@ As an AI assistant user, I want to get a high-level summary of the project sched
 - Q: What happens when any query tool is called without a file loaded? → A: Return informative error indicating no XER file is loaded; applies to all tools except load_xer
 - Q: Should project summary include the data date? → A: Yes, include the data date (schedule "as-of" date) in project summary response
 - Q: Should relationship queries return the driving flag? → A: Yes, include the driving property in all relationship responses (predecessors, successors, list relationships)
+- Q: Which milestone types should be included in milestone queries? → A: Include both Start Milestones and Finish Milestones

 ## Assumptions

--- a/specs/001-schedule-tools/tasks.md
+++ b/specs/001-schedule-tools/tasks.md
@@ -1,16 +1,18 @@
-# Tasks: Add Driving Flag to Relationships
+# Tasks: Add Milestone Type to List Milestones Tool

 **Input**: Design documents from `/specs/001-schedule-tools/`
 **Prerequisites**: plan.md (required), spec.md (required), research.md, data-model.md, contracts/

 **Tests**: TDD is mandated by constitution - tests MUST be written and fail before implementation.

-**Scope**: Enhancement to existing implementation - add computed `driving` flag to relationship query responses.
+**Scope**: Enhancement to existing implementation - add `milestone_type` (start/finish) to milestone query responses per spec clarification.
+
+**Change Summary**: The spec was updated to require that the `list_milestones` tool return both Start Milestones and Finish Milestones with their `milestone_type` field (start/finish for milestones, null otherwise).

 ## Format: `[ID] [P?] [Story] Description`

 - **[P]**: Can run in parallel (different files, no dependencies)
- **[Story]**: Which user story this task belongs to (US3 = Query Activity Relationships)
+- **[Story]**: Which user story this task belongs to (US4 = Query Project Summary)
 - Include exact file paths in descriptions

 ## Path Conventions
@@ -23,65 +25,70 @@

 ## Phase 1: Setup (Schema Enhancement)

-**Purpose**: Add early date columns needed for driving flag computation
+**Purpose**: Add milestone_type column needed for distinguishing start vs finish milestones

- [x] T001 Update activities table schema to add early_start_date and early_end_date columns in src/xer_mcp/db/schema.py
+- [x] T001 Update activities table schema to add milestone_type column in src/xer_mcp/db/schema.py

 ---

 ## Phase 2: Foundational (Parser Enhancement)

-**Purpose**: Parse early dates from TASK table and store in database
+**Purpose**: Parse milestone_type from TASK table and store in database

-**⚠️ CRITICAL**: Must complete before relationship queries can compute driving flag
+**⚠️ CRITICAL**: Must complete before milestone queries can return the type

 ### Tests

- [x] T002 [P] Unit test for TASK handler parsing early dates in tests/unit/test_table_handlers.py (verify early_start_date, early_end_date extracted)
+- [x] T002 [P] Unit test for TASK handler parsing milestone_type in tests/unit/test_table_handlers.py (verify milestone_type extracted for TT_Mile activities)

 ### Implementation

- [x] T003 Update TASK table handler to parse early_start_date and early_end_date in src/xer_mcp/parser/table_handlers/task.py
- [x] T004 Update database loader to store early dates when inserting activities in src/xer_mcp/db/loader.py
+- [x] T003 Update TASK table handler to parse milestone_type field in src/xer_mcp/parser/table_handlers/task.py
+- [x] T004 Update database loader to store milestone_type when inserting activities in src/xer_mcp/db/loader.py

-**Checkpoint**: Early dates are now parsed and stored - driving computation can begin
+**Checkpoint**: milestone_type is now parsed and stored - queries can begin

 ---

-## Phase 3: User Story 3 - Add Driving Flag to Relationships (Priority: P2) 🎯 FOCUS
+## Phase 3: User Story 4 - Add Milestone Type to Queries (Priority: P3)

-**Goal**: Compute and return `driving` flag in all relationship query responses
+**Goal**: Return `milestone_type` field in milestone query responses

-**Independent Test**: Load XER file, query relationships, verify driving flag is present and correctly computed
+**Independent Test**: Load XER file, query milestones, verify milestone_type is present and correctly identifies start vs finish milestones

-### Tests for User Story 3
+### Tests for User Story 4

 > **NOTE: Write these tests FIRST, ensure they FAIL before implementation**

- [x] T005 [P] [US3] Update contract test to verify driving flag in list_relationships response in tests/contract/test_list_relationships.py
- [x] T006 [P] [US3] Update contract test to verify driving flag in get_predecessors response in tests/contract/test_get_predecessors.py
- [x] T007 [P] [US3] Update contract test to verify driving flag in get_successors response in tests/contract/test_get_successors.py
- [x] T008 [P] [US3] Unit test for driving flag computation logic in tests/unit/test_db_queries.py (test is_driving_relationship function)
+- [x] T005 [P] [US4] Update contract test to verify milestone_type field in list_milestones response in tests/contract/test_list_milestones.py
+- [x] T006 [P] [US4] Add test case verifying both start and finish milestones are returned with correct types in tests/contract/test_list_milestones.py

-### Implementation for User Story 3
+### Implementation for User Story 4

- [x] T009 [US3] Create is_driving_relationship helper function in src/xer_mcp/db/queries.py (implements date comparison logic from research.md)
- [x] T010 [US3] Update query_relationships function to JOIN on activity early dates and compute driving flag in src/xer_mcp/db/queries.py
- [x] T011 [US3] Update get_predecessors function to JOIN on activity early dates and compute driving flag in src/xer_mcp/db/queries.py
- [x] T012 [US3] Update get_successors function to JOIN on activity early dates and compute driving flag in src/xer_mcp/db/queries.py
+- [x] T007 [US4] Update query_milestones function to SELECT and return milestone_type in src/xer_mcp/db/queries.py
+- [x] T008 [US4] Update list_milestones tool docstring to document milestone_type field in src/xer_mcp/tools/list_milestones.py

-**Checkpoint**: Driving flag now included in all relationship responses
+**Checkpoint**: milestone_type now included in milestone responses

 ---

-## Phase 4: Polish & Validation
+## Phase 4: Documentation & Contracts

-**Purpose**: Verify integration and documentation alignment
+**Purpose**: Update contracts and documentation to reflect the new field

- [x] T013 Integration test validating driving flag against sample XER data in tests/integration/test_xer_parsing.py
- [x] T014 Run all tests to verify no regressions: pytest tests/
- [x] T015 Run quickstart.md validation - verify driving flag examples match actual output
- [x] T016 Run ruff check and fix any linting issues: ruff check src/
+- [x] T009 [P] Update ActivitySummary schema to include optional milestone_type field in specs/001-schedule-tools/contracts/mcp-tools.json
+- [x] T010 [P] Update Activity entity in data-model.md to include milestone_type field in specs/001-schedule-tools/data-model.md
+- [x] T011 Update quickstart.md milestone example to show milestone_type in output in specs/001-schedule-tools/quickstart.md
+
+---
+
+## Phase 5: Polish & Validation
+
+**Purpose**: Verify integration and ensure no regressions
+
+- [x] T012 Run all tests to verify no regressions: uv run pytest tests/
+- [x] T013 Run ruff check and fix any linting issues: uv run ruff check src/
+- [x] T014 Validate list_milestones output matches updated contract schema

 ---

@@ -99,107 +106,106 @@ Phase 2 (Parser)
 Phase 3 (Queries) ← MAIN WORK
    │
    ▼
-Phase 4 (Polish)
-```
-
-### Task Dependencies Within Phase 3
-
-```
-T005, T006, T007, T008 (Tests) ← Write first, verify FAIL
+Phase 4 (Docs) ← Can run in parallel with Phase 3
    │
    ▼
-T009 (Helper function)
+Phase 5 (Polish)
+```
+
+### Task Dependencies Within Phases
+
+```
+T001 (Schema)
    │
-    ├── T010 (query_relationships)
-    ├── T011 (get_predecessors)
-    └── T012 (get_successors)
+    ├── T002 (Parser test)
    │
    ▼
-All tests now PASS
+T003 (Parser impl) ← depends on T001
+    │
+    ▼
+T004 (Loader) ← depends on T003
+    │
+    ├── T005, T006 (Contract tests)
+    │
+    ▼
+T007 (Query impl) ← depends on T004
+    │
+    ▼
+T008 (Tool docs)
 ```

 ### Parallel Opportunities

 **Phase 2 Tests + Phase 3 Tests** (can write all tests in parallel):
 ```bash
-# All test tasks can run in parallel:
-Task T002: "Unit test for TASK handler parsing early dates"
-Task T005: "Update contract test for list_relationships"
-Task T006: "Update contract test for get_predecessors"
-Task T007: "Update contract test for get_successors"
-Task T008: "Unit test for driving flag computation"
+Task T002: "Unit test for TASK handler parsing milestone_type"
+Task T005: "Update contract test for list_milestones"
+Task T006: "Add test for start/finish milestone types"
 ```

-**Phase 3 Query Updates** (after T009 is complete):
+**Phase 4 Documentation** (can run in parallel):
 ```bash
-# These can run in parallel once helper function exists:
-Task T010: "Update query_relationships"
-Task T011: "Update get_predecessors"
-Task T012: "Update get_successors"
+Task T009: "Update ActivitySummary schema"
+Task T010: "Update Activity entity in data-model.md"
+Task T011: "Update quickstart.md example"
 ```

 ---

-## Parallel Example: Phase 3
+## Implementation Details

-```bash
-# First: Write all tests in parallel
-Task: "Update contract test for list_relationships in tests/contract/test_list_relationships.py"
-Task: "Update contract test for get_predecessors in tests/contract/test_get_predecessors.py"
-Task: "Update contract test for get_successors in tests/contract/test_get_successors.py"
-Task: "Unit test for driving flag computation in tests/unit/test_db_queries.py"
+### Milestone Type Determination

-# Verify all tests FAIL (driving flag not yet implemented)
+In Primavera P6, milestones are identified by `task_type = 'TT_Mile'`. The distinction between Start and Finish milestones is typically:

-# Then: Implement helper function
-Task: "Create is_driving_relationship helper in src/xer_mcp/db/queries.py"
+1. **XER Field**: Check for `milestone_type` field in TASK table (values: `MS_Start`, `MS_Finish`)
+2. **Fallback**: If field not present, can infer from dates:
+   - Start milestone: Has only `target_start_date` (or start = end)
+   - Finish milestone: Has only `target_end_date` (or represents completion)

-# Then: Update all queries in parallel
-Task: "Update query_relationships in src/xer_mcp/db/queries.py"
-Task: "Update get_predecessors in src/xer_mcp/db/queries.py"
-Task: "Update get_successors in src/xer_mcp/db/queries.py"
-
-# Verify all tests PASS
-```
-
---
-
-## Implementation Strategy
-
-### Driving Flag Computation (from research.md)
-
-The driving flag is computed at query time by comparing dates:
-
-```python
-def is_driving_relationship(
-    pred_early_end: str | None,
-    succ_early_start: str | None,
-    lag_hours: float,
-    pred_type: str
-) -> bool:
-    """Determine if relationship is driving based on early dates."""
-    if pred_early_end is None or succ_early_start is None:
-        return False
-
-    # For FS: pred_end + lag = succ_start means driving
-    if pred_type == "FS":
-        # Parse dates, add lag, compare with 1-hour tolerance
-        ...
-
-    # Similar logic for SS, FF, SF
-    return False
-```
-
-### SQL Query Pattern
+### Schema Change

 ```sql
-SELECT r.*,
-       pred.early_end_date,
-       succ.early_start_date,
-       -- Compute driving in Python after fetch, or use CASE in SQL
-FROM relationships r
-JOIN activities pred ON r.pred_task_id = pred.task_id
-JOIN activities succ ON r.task_id = succ.task_id
+-- Add to activities table
+milestone_type TEXT  -- 'start', 'finish', or NULL for non-milestones
+```
+
+### Query Change
+
+```sql
+SELECT task_id, task_code, task_name,
+       target_start_date, target_end_date,
+       status_code, milestone_type
+FROM activities
+WHERE task_type = 'TT_Mile'
+ORDER BY target_start_date, task_code
+```
+
+### Response Format
+
+```json
+{
+  "milestones": [
+    {
+      "task_id": "M001",
+      "task_code": "MS-START",
+      "task_name": "Project Start",
+      "milestone_type": "start",
+      "target_start_date": "2026-01-15T08:00:00",
+      "target_end_date": "2026-01-15T08:00:00",
+      "status_code": "TK_Complete"
+    },
+    {
+      "task_id": "M002",
+      "task_code": "MS-END",
+      "task_name": "Project Complete",
+      "milestone_type": "finish",
+      "target_start_date": "2026-06-30T17:00:00",
+      "target_end_date": "2026-06-30T17:00:00",
+      "status_code": "TK_NotStart"
+    }
+  ]
+}
 ```

 ---
@@ -210,30 +216,40 @@ JOIN activities succ ON r.task_id = succ.task_id
 |-------|-------|-------|
 | Setup | 1 | Schema update |
 | Foundational | 3 | Parser enhancement |
-| US3 Implementation | 8 | Driving flag computation |
-| Polish | 4 | Validation |
-| **Total** | **16** | |
+| US4 Implementation | 4 | Milestone type in queries |
+| Documentation | 3 | Contracts & docs |
+| Polish | 3 | Validation |
+| **Total** | **14** | |

 ### Task Distribution by Type

 | Type | Count | IDs |
 |------|-------|-----|
 | Schema | 1 | T001 |
-| Tests | 5 | T002, T005-T008 |
-| Implementation | 6 | T003-T004, T009-T012 |
-| Validation | 4 | T013-T016 |
+| Tests | 3 | T002, T005, T006 |
+| Implementation | 4 | T003, T004, T007, T008 |
+| Documentation | 3 | T009, T010, T011 |
+| Validation | 3 | T012, T013, T014 |
+
+### Independent Test Criteria
+
+| Verification | How to Test |
+|--------------|-------------|
+| milestone_type parsed | Unit test: parse XER with milestones, verify milestone_type extracted |
+| milestone_type in response | Contract test: call list_milestones, verify milestone_type field present |
+| Start/Finish distinction | Contract test: verify "Project Start" has type="start", "Project Complete" has type="finish" |

 ### MVP Scope

-Complete through T012 for minimal viable driving flag implementation.
+Complete through T008 for minimal viable milestone_type implementation.

 ---

 ## Notes

 - [P] tasks = different files, no dependencies on incomplete tasks
- [US3] = User Story 3 (Query Activity Relationships)
+- [US4] = User Story 4 (Query Project Summary - milestones)
 - Constitution mandates TDD: write tests first, verify they fail, then implement
- Driving flag is COMPUTED at query time, not stored in database
- Use 1-hour tolerance for floating-point date arithmetic
+- milestone_type is stored in database, not computed at query time
+- For non-milestone activities, milestone_type should be NULL
 - Commit after each task or logical group
--- a/specs/002-direct-db-access/checklists/requirements.md
+++ b/specs/002-direct-db-access/checklists/requirements.md
@@ -0,0 +1,37 @@
+# Specification Quality Checklist: Direct Database Access for Scripts
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-08
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass validation
+- Spec is ready for `/speckit.clarify` or `/speckit.plan`
+- The feature cleanly extends existing functionality (load_xer) with persistent database output
+- Assumptions section documents reasonable defaults for database location and persistence behavior
--- a/specs/002-direct-db-access/contracts/mcp-tools.json
+++ b/specs/002-direct-db-access/contracts/mcp-tools.json
@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "XER MCP Server Tools - Direct Database Access Extension",
+  "description": "MCP tool definitions for persistent database access",
+  "version": "0.2.0",
+  "tools": [
+    {
+      "name": "load_xer",
+      "description": "Load a Primavera P6 XER file and parse its schedule data. Optionally persist to a SQLite database file for direct script access.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file_path": {
+            "type": "string",
+            "description": "Absolute path to the XER file"
+          },
+          "project_id": {
+            "type": "string",
+            "description": "Project ID to select (required for multi-project files)"
+          },
+          "db_path": {
+            "type": "string",
+            "description": "Path for persistent SQLite database file. If omitted, uses in-memory database. If empty string, auto-generates path from XER filename (same directory, .sqlite extension)."
+          }
+        },
+        "required": ["file_path"]
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean" },
+          "project": {
+            "type": "object",
+            "properties": {
+              "proj_id": { "type": "string" },
+              "proj_short_name": { "type": "string" },
+              "plan_start_date": { "type": "string", "format": "date-time" },
+              "plan_end_date": { "type": "string", "format": "date-time" }
+            }
+          },
+          "activity_count": { "type": "integer" },
+          "relationship_count": { "type": "integer" },
+          "database": { "$ref": "#/$defs/DatabaseInfo" },
+          "available_projects": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "proj_id": { "type": "string" },
+                "proj_short_name": { "type": "string" }
+              }
+            },
+            "description": "Only present for multi-project files without selection"
+          },
+          "warnings": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    {
+      "name": "get_database_info",
+      "description": "Get information about the currently loaded database including file path and schema. Use this to get connection details for direct SQL access.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "database": { "$ref": "#/$defs/DatabaseInfo" },
+          "error": { "$ref": "#/$defs/Error" }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "DatabaseInfo": {
+      "type": "object",
+      "properties": {
+        "db_path": {
+          "type": "string",
+          "description": "Absolute path to SQLite database file, or ':memory:' for in-memory"
+        },
+        "is_persistent": {
+          "type": "boolean",
+          "description": "True if file-based database, false if in-memory"
+        },
+        "source_file": {
+          "type": "string",
+          "description": "Path to XER file that was loaded"
+        },
+        "loaded_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When data was loaded"
+        },
+        "schema": { "$ref": "#/$defs/SchemaInfo" }
+      },
+      "required": ["db_path", "is_persistent", "loaded_at", "schema"]
+    },
+    "SchemaInfo": {
+      "type": "object",
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "Schema version"
+        },
+        "tables": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/TableInfo" }
+        }
+      },
+      "required": ["version", "tables"]
+    },
+    "TableInfo": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "columns": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ColumnInfo" }
+        },
+        "primary_key": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "foreign_keys": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/ForeignKeyInfo" }
+        },
+        "row_count": { "type": "integer" }
+      },
+      "required": ["name", "columns", "primary_key", "row_count"]
+    },
+    "ColumnInfo": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "nullable": { "type": "boolean" },
+        "default": { "type": "string" }
+      },
+      "required": ["name", "type", "nullable"]
+    },
+    "ForeignKeyInfo": {
+      "type": "object",
+      "properties": {
+        "column": { "type": "string" },
+        "references_table": { "type": "string" },
+        "references_column": { "type": "string" }
+      },
+      "required": ["column", "references_table", "references_column"]
+    },
+    "Error": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "enum": ["NO_FILE_LOADED", "DATABASE_ERROR", "FILE_NOT_WRITABLE", "DISK_FULL"]
+        },
+        "message": { "type": "string" }
+      },
+      "required": ["code", "message"]
+    }
+  }
+}
--- a/specs/002-direct-db-access/data-model.md
+++ b/specs/002-direct-db-access/data-model.md
@@ -0,0 +1,181 @@
+# Data Model: Direct Database Access for Scripts
+
+**Date**: 2026-01-08
+**Branch**: `002-direct-db-access`
+
+## Entity Overview
+
+```
+┌─────────────────┐
+│  DatabaseInfo   │
+└─────────────────┘
+        │
+        ▼
+┌─────────────────┐       ┌─────────────────┐
+│   SchemaInfo    │───────│   TableInfo     │
+└─────────────────┘       └─────────────────┘
+                                  │
+                                  ▼
+                          ┌─────────────────┐
+                          │   ColumnInfo    │
+                          └─────────────────┘
+```
+
+## New Entities
+
+### DatabaseInfo
+
+Information about the current database connection, returned by load operations and queryable separately.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| db_path | string | Yes | Absolute path to SQLite database file; `:memory:` for in-memory |
+| is_persistent | boolean | Yes | True if file-based, false if in-memory |
+| source_file | string | No | Path to XER file that was loaded |
+| loaded_at | datetime | Yes | When data was loaded |
+| schema | SchemaInfo | Yes | Database schema information |
+
+**Validation Rules**:
+- db_path must be an absolute path (or `:memory:`)
+- loaded_at must be ISO 8601 format
+
+### SchemaInfo
+
+Metadata describing the database structure.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| tables | list[TableInfo] | Yes | All tables in the database |
+| version | string | Yes | Schema version (matches server version) |
+
+### TableInfo
+
+Information about a single database table.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Table name |
+| columns | list[ColumnInfo] | Yes | Column definitions |
+| primary_key | list[string] | Yes | Column(s) forming primary key |
+| foreign_keys | list[ForeignKeyInfo] | No | Foreign key relationships |
+| row_count | integer | Yes | Number of rows in table |
+
+### ColumnInfo
+
+Information about a single column.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Column name |
+| type | string | Yes | SQLite data type (TEXT, INTEGER, REAL, etc.) |
+| nullable | boolean | Yes | Whether NULL values are allowed |
+| default | string | No | Default value if any |
+
+### ForeignKeyInfo
+
+Foreign key relationship information.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| column | string | Yes | Column in this table |
+| references_table | string | Yes | Referenced table |
+| references_column | string | Yes | Referenced column |
+
+## Extended load_xer Response
+
+The existing load_xer tool response is extended with database information:
+
+```json
+{
+  "success": true,
+  "project": { ... },
+  "activity_count": 4440,
+  "relationship_count": 8583,
+  "database": {
+    "db_path": "/path/to/schedule.sqlite",
+    "is_persistent": true,
+    "source_file": "/path/to/schedule.xer",
+    "loaded_at": "2026-01-08T14:30:00",
+    "schema": {
+      "version": "0.2.0",
+      "tables": [
+        {
+          "name": "activities",
+          "columns": [
+            {"name": "task_id", "type": "TEXT", "nullable": false},
+            {"name": "task_name", "type": "TEXT", "nullable": false},
+            ...
+          ],
+          "primary_key": ["task_id"],
+          "foreign_keys": [
+            {"column": "proj_id", "references_table": "projects", "references_column": "proj_id"}
+          ],
+          "row_count": 4440
+        },
+        ...
+      ]
+    }
+  }
+}
+```
+
+## New Tool Input Schema
+
+### load_xer (extended)
+
+New optional parameter:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| db_path | string | No | Path for persistent database file. If omitted, uses in-memory database. If empty string, auto-generates path from XER filename. |
+
+### get_database_info
+
+No input parameters required. Returns current database information.
+
+## SQLite Schema (Unchanged)
+
+The underlying database schema remains unchanged from feature 001-schedule-tools:
+
+- `projects` - Project metadata
+- `activities` - Task/activity data
+- `relationships` - Predecessor/successor relationships
+- `wbs` - Work breakdown structure
+- `calendars` - Calendar definitions
+
+The difference is storage location (file vs memory), not structure.
+
+## Query Examples for Scripts
+
+Once scripts have the database path, they can execute standard SQL:
+
+```python
+import sqlite3
+
+# Connect using path from load_xer response
+conn = sqlite3.connect("/path/to/schedule.sqlite")
+
+# Query activities
+cursor = conn.execute("""
+    SELECT task_code, task_name, target_start_date, target_end_date
+    FROM activities
+    WHERE task_type = 'TT_Mile'
+    ORDER BY target_start_date
+""")
+
+for row in cursor:
+    print(row)
+```
+
+```sql
+-- Find critical path activities
+SELECT task_code, task_name, total_float_hr_cnt
+FROM activities
+WHERE driving_path_flag = 1
+ORDER BY target_start_date;
+
+-- Join activities with WBS
+SELECT a.task_code, a.task_name, w.wbs_name
+FROM activities a
+JOIN wbs w ON a.wbs_id = w.wbs_id;
+```
--- a/specs/002-direct-db-access/plan.md
+++ b/specs/002-direct-db-access/plan.md
@@ -0,0 +1,108 @@
+# Implementation Plan: Direct Database Access for Scripts
+
+**Branch**: `002-direct-db-access` | **Date**: 2026-01-08 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/002-direct-db-access/spec.md`
+
+## Summary
+
+Extend the XER MCP Server to support persistent SQLite database files instead of only in-memory databases. The existing `load_xer` tool will gain an optional parameter to write to a file-based database, and the response will include the database path and schema information. A new `get_database_info` tool will allow retrieval of database connection details without reloading. This enables scripts to query schedule data directly via SQL, reducing LLM workload for large data processing.
+
+## Technical Context
+
+**Language/Version**: Python 3.14
+**Primary Dependencies**: mcp>=1.0.0 (MCP SDK), sqlite3 (stdlib)
+**Storage**: SQLite database file (persistent) in addition to existing in-memory option
+**Testing**: pytest>=8.0.0, pytest-asyncio>=0.24.0
+**Target Platform**: Local server (Linux/macOS/Windows with file system access)
+**Project Type**: Single project (extending existing structure)
+**Performance Goals**: Database file creation <1 second; query response <100ms for 10,000+ activities
+**Constraints**: File must be accessible by external scripts; atomic writes to prevent corruption
+**Scale/Scope**: 2 MCP tools modified/added; extends existing database layer
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Requirement | Status | Notes |
+|-----------|-------------|--------|-------|
+| **I. Test-First Development** | TDD mandatory; tests fail before implementation | ✅ PASS | Contract tests for modified load_xer and new get_database_info tool |
+| **II. Extensibility Architecture** | Core parsing separate from MCP transport; pluggable handlers | ✅ PASS | Extends existing DatabaseManager; no changes to parser or handlers |
+| **III. MCP Protocol Compliance** | Complete JSON schemas; MCP error format; compliant transport | ✅ PASS | New tool definitions include JSON schemas; error responses follow MCP format |
+| **IV. XER Format Fidelity** | No data loss; preserve precision; handle all standard tables | ✅ PASS | Same data written to file-based DB as in-memory; no parsing changes |
+| **V. Semantic Versioning** | SemVer for releases; breaking changes documented | ✅ PASS | Minor version bump (0.2.0); backward compatible - existing behavior unchanged |
+| **Technical Standards** | Python 3.14; type hints; ruff formatting | ✅ PASS | Follows existing codebase patterns |
+
+**Gate Result**: PASS - All constitution principles satisfied. Proceed to Phase 0.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-direct-db-access/
+├── spec.md              # Feature specification
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+```text
+src/xer_mcp/
+├── db/
+│   ├── __init__.py          # Modify DatabaseManager for file-based DB support
+│   ├── schema.py            # No changes needed
+│   ├── loader.py            # No changes needed
+│   └── queries.py           # Add schema introspection query
+└── tools/
+    ├── load_xer.py          # Modify to support db_path parameter and return schema
+    └── get_database_info.py # NEW: Return database path and schema info
+
+tests/
+├── contract/
+│   ├── test_load_xer.py     # Add tests for persistent database functionality
+│   └── test_get_database_info.py  # NEW: Contract tests for schema retrieval
+└── unit/
+    └── test_db_manager.py   # NEW: Unit tests for file-based database operations
+```
+
+**Structure Decision**: Extends existing single project structure. Minimal changes to existing modules; adds one new tool file and modifies DatabaseManager to support both in-memory and file-based databases.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+No violations. All constitution principles satisfied.
+
+## Post-Design Constitution Re-Check
+
+*Re-evaluation after Phase 1 design artifacts are complete.*
+
+| Principle | Status | Verification |
+|-----------|--------|--------------|
+| **I. Test-First Development** | ✅ PASS | Contract tests for load_xer db_path parameter; contract tests for get_database_info tool |
+| **II. Extensibility Architecture** | ✅ PASS | DatabaseManager extended without breaking existing interface; new tool follows existing patterns |
+| **III. MCP Protocol Compliance** | ✅ PASS | Tool schemas defined in contracts/mcp-tools.json; error responses use existing MCP error format |
+| **IV. XER Format Fidelity** | ✅ PASS | No changes to parsing; same data fidelity in file-based DB as in-memory |
+| **V. Semantic Versioning** | ✅ PASS | Version 0.2.0; new feature, backward compatible |
+| **Technical Standards** | ✅ PASS | Type hints; ruff formatting; pytest async tests |
+
+**Post-Design Gate Result**: PASS - Design artifacts align with constitution. Ready for task generation.
+
+## Generated Artifacts
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| Research | `specs/002-direct-db-access/research.md` | SQLite file vs in-memory, atomic writes, schema introspection |
+| Data Model | `specs/002-direct-db-access/data-model.md` | DatabaseInfo entity, SchemaInfo structure |
+| Contracts | `specs/002-direct-db-access/contracts/mcp-tools.json` | Updated load_xer schema, new get_database_info schema |
+| Quickstart | `specs/002-direct-db-access/quickstart.md` | Usage examples for direct database access |
+| Agent Context | `CLAUDE.md` | No updates needed (same technologies) |
+
+## Next Steps
+
+Run `/speckit.tasks` to generate implementation tasks from this plan.
--- a/specs/002-direct-db-access/quickstart.md
+++ b/specs/002-direct-db-access/quickstart.md
@@ -0,0 +1,189 @@
+# Quickstart: Direct Database Access for Scripts
+
+This guide shows how to use the XER MCP Server's persistent database feature to query schedule data directly from scripts.
+
+## Overview
+
+The XER MCP Server can save parsed schedule data to a SQLite file, allowing your scripts to query the data directly without going through MCP tools. This is ideal for:
+
+- Large-scale data analysis
+- Custom reporting
+- Integration with other tools
+- Reducing LLM token usage for data-heavy operations
+
+## Loading to a Persistent Database
+
+### Option 1: Auto-generated Path
+
+Use an empty string for `db_path` to automatically create a database file alongside the XER file:
+
+```
+Use the load_xer tool with file_path="/path/to/schedule.xer" and db_path=""
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "project": {
+    "proj_id": "P001",
+    "proj_short_name": "Construction Phase 1"
+  },
+  "activity_count": 4440,
+  "database": {
+    "db_path": "/path/to/schedule.sqlite",
+    "is_persistent": true,
+    "source_file": "/path/to/schedule.xer",
+    "loaded_at": "2026-01-08T14:30:00",
+    "schema": {
+      "version": "0.2.0",
+      "tables": [
+        {
+          "name": "activities",
+          "columns": [
+            {"name": "task_id", "type": "TEXT", "nullable": false},
+            {"name": "task_code", "type": "TEXT", "nullable": false},
+            {"name": "task_name", "type": "TEXT", "nullable": false},
+            ...
+          ],
+          "row_count": 4440
+        },
+        ...
+      ]
+    }
+  }
+}
+```
+
+### Option 2: Specify Custom Path
+
+```
+Use the load_xer tool with file_path="/path/to/schedule.xer" and db_path="/data/my-schedule.db"
+```
+
+### Option 3: In-Memory Only (Default)
+
+Omit `db_path` to use the original in-memory behavior:
+
+```
+Use the load_xer tool with file_path="/path/to/schedule.xer"
+```
+
+## Querying the Database Directly
+
+Once you have the database path, use any SQLite client to query the data.
+
+### Python Example
+
+```python
+import sqlite3
+
+# Use the db_path from load_xer response
+db_path = "/path/to/schedule.sqlite"
+
+conn = sqlite3.connect(db_path)
+conn.row_factory = sqlite3.Row
+
+# Query all milestones
+cursor = conn.execute("""
+    SELECT task_code, task_name, target_start_date, milestone_type
+    FROM activities
+    WHERE task_type IN ('TT_Mile', 'TT_FinMile')
+    ORDER BY target_start_date
+""")
+
+for row in cursor:
+    print(f"{row['task_code']}: {row['task_name']} ({row['milestone_type']})")
+
+conn.close()
+```
+
+### SQL Examples
+
+**Find critical path activities:**
+```sql
+SELECT task_code, task_name, target_start_date, target_end_date
+FROM activities
+WHERE driving_path_flag = 1
+ORDER BY target_start_date;
+```
+
+**Get activity count by WBS:**
+```sql
+SELECT w.wbs_name, COUNT(*) as activity_count
+FROM activities a
+JOIN wbs w ON a.wbs_id = w.wbs_id
+GROUP BY w.wbs_id
+ORDER BY activity_count DESC;
+```
+
+**Find activities with predecessors:**
+```sql
+SELECT a.task_code, a.task_name,
+       COUNT(r.pred_task_id) as predecessor_count
+FROM activities a
+LEFT JOIN relationships r ON a.task_id = r.task_id
+GROUP BY a.task_id
+HAVING predecessor_count > 0
+ORDER BY predecessor_count DESC;
+```
+
+**Export milestones to CSV (using sqlite3 CLI):**
+```bash
+sqlite3 -header -csv schedule.sqlite \
+  "SELECT task_code, task_name, target_start_date, milestone_type
+   FROM activities
+   WHERE task_type IN ('TT_Mile', 'TT_FinMile')" > milestones.csv
+```
+
+## Getting Database Info Without Reloading
+
+If you need the database path and schema later:
+
+```
+Use the get_database_info tool
+```
+
+**Response**:
+```json
+{
+  "database": {
+    "db_path": "/path/to/schedule.sqlite",
+    "is_persistent": true,
+    "source_file": "/path/to/schedule.xer",
+    "loaded_at": "2026-01-08T14:30:00",
+    "schema": { ... }
+  }
+}
+```
+
+## Database Schema Reference
+
+| Table | Description | Key Columns |
+|-------|-------------|-------------|
+| `projects` | Project metadata | proj_id, proj_short_name, plan_start_date, plan_end_date |
+| `activities` | Tasks and milestones | task_id, task_code, task_name, task_type, target_start_date, target_end_date |
+| `relationships` | Predecessor/successor links | task_pred_id, task_id, pred_task_id, pred_type, lag_hr_cnt |
+| `wbs` | Work breakdown structure | wbs_id, wbs_name, parent_wbs_id |
+| `calendars` | Calendar definitions | clndr_id, clndr_name, day_hr_cnt |
+
+## Best Practices
+
+1. **Use persistent database for large schedules**: Schedules with 1000+ activities benefit from direct SQL queries
+
+2. **Close connections when done**: Always close your database connections to avoid lock issues
+
+3. **Read-only access recommended**: The database is designed for reading; modifications may cause inconsistencies with MCP tools
+
+4. **Re-load when XER changes**: If the source XER file is updated, reload to refresh the database
+
+5. **Check schema version**: The schema version in the response indicates compatibility with your queries
+
+## Error Handling
+
+| Error Code | Meaning | Solution |
+|------------|---------|----------|
+| NO_FILE_LOADED | No XER file has been loaded | Call load_xer first |
+| FILE_NOT_WRITABLE | Cannot write database file | Check directory permissions |
+| DISK_FULL | Insufficient disk space | Free up disk space |
+| DATABASE_ERROR | General database error | Check error message for details |
--- a/specs/002-direct-db-access/research.md
+++ b/specs/002-direct-db-access/research.md
@@ -0,0 +1,110 @@
+# Research: Direct Database Access for Scripts
+
+**Date**: 2026-01-08
+**Branch**: `002-direct-db-access`
+
+## Research Topics
+
+### 1. SQLite File-Based vs In-Memory Database
+
+**Decision**: Support both file-based and in-memory databases through the same DatabaseManager interface.
+
+**Rationale**:
+- File-based SQLite allows external scripts to query data directly without MCP overhead
+- In-memory remains the default for backward compatibility with existing tools
+- SQLite's file format is universally readable (Python sqlite3, DBeaver, sqlitebrowser, etc.)
+- Single connection string change (`:memory:` vs file path) switches modes
+
+**Alternatives Considered**:
+- **Separate database manager for files**: Rejected - unnecessary duplication; SQLite handles both modes identically
+- **Export to CSV/JSON**: Rejected - loses relational structure; no query capability
+- **Network database (PostgreSQL)**: Rejected - overkill for single-user local access; requires external server
+
+### 2. Database File Location Strategy
+
+**Decision**: Accept user-specified path, or default to a predictable location derived from the XER file path.
+
+**Rationale**:
+- User-specified path gives maximum flexibility for script integration
+- Default path (`{xer_file_directory}/{xer_basename}.sqlite`) is predictable and colocated with source
+- Absolute paths in responses eliminate ambiguity for scripts
+
+**Default Path Algorithm**:
+```
+Input:  /path/to/schedule.xer
+Output: /path/to/schedule.sqlite
+```
+
+**Alternatives Considered**:
+- **Temp directory only**: Rejected - less predictable; may be cleaned up unexpectedly
+- **Fixed location (e.g., ~/.xer-mcp/db/)**: Rejected - less convenient; separates DB from source file
+- **Always require user to specify**: Rejected - worse developer experience for common case
+
+### 3. Atomic Write Strategy
+
+**Decision**: Use SQLite's built-in transaction support; write to temp file and rename for atomicity.
+
+**Rationale**:
+- SQLite transactions ensure data integrity during writes
+- Write-then-rename pattern prevents partial/corrupted files if process interrupted
+- External scripts won't see incomplete data
+
+**Implementation**:
+1. Create database at `{target_path}.tmp`
+2. Load all data within a transaction
+3. Commit transaction
+4. Rename `{target_path}.tmp` to `{target_path}` (atomic on POSIX)
+
+**Alternatives Considered**:
+- **Direct write to final path**: Rejected - risk of corruption on interruption
+- **Lock file mechanism**: Rejected - SQLite already handles locking; adds complexity
+
+### 4. Schema Introspection Approach
+
+**Decision**: Query SQLite's `sqlite_master` table and `PRAGMA table_info()` for schema information.
+
+**Rationale**:
+- Standard SQLite introspection APIs - no custom metadata needed
+- Returns actual schema, not just documentation
+- Works with any SQLite database, even if created by different tools
+
+**Schema Information Returned**:
+- Table names
+- Column names and types for each table
+- Primary key information
+- Foreign key relationships (via `PRAGMA foreign_key_list()`)
+
+**Alternatives Considered**:
+- **Hardcoded schema in response**: Rejected - may drift from actual schema; not dynamic
+- **Separate metadata table**: Rejected - adds complexity; standard introspection sufficient
+
+### 5. Concurrent Access Handling
+
+**Decision**: Use SQLite WAL (Write-Ahead Logging) mode for concurrent read access.
+
+**Rationale**:
+- WAL mode allows multiple readers while one writer operates
+- Scripts can query while MCP server operates without blocking
+- Minimal configuration change: `PRAGMA journal_mode=WAL`
+
+**Implementation**:
+- Enable WAL mode when creating file-based database
+- In-memory databases don't need WAL (single connection)
+
+**Alternatives Considered**:
+- **Reader/writer locks in application**: Rejected - SQLite handles this natively
+- **Copy-on-read**: Rejected - unnecessary with WAL mode
+
+## Technology Decisions Summary
+
+| Decision | Choice | Key Reason |
+|----------|--------|------------|
+| Database format | SQLite file | Universal compatibility, no server needed |
+| Default location | Same directory as XER file | Predictable, colocated |
+| Atomicity | Temp file + rename | Prevents corruption |
+| Schema info | SQLite introspection APIs | Dynamic, accurate |
+| Concurrency | WAL mode | Multiple readers supported |
+
+## Open Questions Resolved
+
+All technical questions have been resolved through research. No clarifications needed.
--- a/specs/002-direct-db-access/spec.md
+++ b/specs/002-direct-db-access/spec.md
@@ -0,0 +1,102 @@
+# Feature Specification: Direct Database Access for Scripts
+
+**Feature Branch**: `002-direct-db-access`
+**Created**: 2026-01-08
+**Status**: Draft
+**Input**: User description: "Create a new feature that allows for scripts to directly query the schedule loaded into the database. The mcp endpoint should be used to load the xer file to a database. The response should provide the necessary information for a script to then access that database directly to perform queries. The intent is to minimize the costly and time-consuming workload on the LLM for large data processing."
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Load XER to Persistent Database (Priority: P1)
+
+As a developer building schedule analysis scripts, I want to load an XER file into a database that persists beyond the MCP session so that my scripts can query the data directly without going through the LLM.
+
+**Why this priority**: This is the foundation of the feature - without a persistent database, scripts cannot access the data directly. This enables the primary use case of offloading large data processing from the LLM.
+
+**Independent Test**: Can be tested by calling the load endpoint and verifying the database file is created at the returned path with the expected schema and data.
+
+**Acceptance Scenarios**:
+
+1. **Given** a valid XER file path, **When** I call the load-to-database endpoint, **Then** the system creates a SQLite database file at a predictable location and returns the database file path
+2. **Given** an XER file is loaded to database, **When** I examine the database file, **Then** it contains all activities, relationships, WBS elements, and project data from the XER file
+3. **Given** a database was previously created for an XER file, **When** I load the same XER file again, **Then** the existing database is replaced with fresh data
+4. **Given** an invalid or non-existent XER file path, **When** I call the load-to-database endpoint, **Then** I receive a clear error message and no database file is created
+
+---
+
+### User Story 2 - Retrieve Database Connection Information (Priority: P1)
+
+As a developer, I want the load response to include all information needed to connect to and query the database so that I can immediately start writing queries in my scripts.
+
+**Why this priority**: Without connection information, developers cannot use the database even if it exists. This is equally critical to the first story.
+
+**Independent Test**: Can be tested by using the returned connection info to successfully open and query the database from an external script.
+
+**Acceptance Scenarios**:
+
+1. **Given** a successful XER load to database, **When** I receive the response, **Then** it includes the absolute path to the database file
+2. **Given** a successful XER load to database, **When** I receive the response, **Then** it includes the database schema description (table names and key columns)
+3. **Given** the returned database path, **When** I connect to it from a Python/SQL script, **Then** I can successfully query activities, relationships, and other schedule data
+
+---
+
+### User Story 3 - Query Database Schema Information (Priority: P2)
+
+As a developer unfamiliar with the database structure, I want to retrieve the database schema so that I can write correct SQL queries without guessing table and column names.
+
+**Why this priority**: While developers can explore the database manually, having schema information readily available improves developer experience and reduces errors.
+
+**Independent Test**: Can be tested by calling the schema endpoint and verifying the returned schema matches the actual database structure.
+
+**Acceptance Scenarios**:
+
+1. **Given** a database has been created, **When** I request the schema, **Then** I receive a list of all tables with their columns and data types
+2. **Given** a database has been created, **When** I request the schema, **Then** I receive information about relationships between tables (foreign keys)
+3. **Given** no database has been created yet, **When** I request the schema, **Then** I receive an informative error indicating no database is available
+
+---
+
+### Edge Cases
+
+- What happens when the disk is full and database cannot be created? Return a clear error message indicating storage issue.
+- What happens when the database file path is not writable? Return a clear error message indicating permission issue.
+- What happens when a script is querying the database while a new XER file is being loaded? The load operation should complete atomically - either fully succeed or fully fail, preventing partial/corrupted reads.
+- What happens when multiple XER files are loaded in sequence? Each load replaces the previous database content; only one project's data is available at a time.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: System MUST provide an MCP tool to load an XER file into a persistent SQLite database file (not just in-memory)
+- **FR-002**: System MUST return the absolute file path to the created database in the load response
+- **FR-003**: System MUST return a summary of the database schema (tables and key columns) in the load response
+- **FR-004**: Database file MUST be stored in a predictable, accessible location that scripts can reach
+- **FR-005**: System MUST preserve all data currently stored by the in-memory database (activities, relationships, WBS, calendars, projects)
+- **FR-006**: System MUST provide an MCP tool to retrieve the current database path and schema without reloading data
+- **FR-007**: System MUST handle concurrent access safely - database remains queryable while MCP tools are used
+- **FR-008**: System MUST return clear errors when database operations fail (file not writable, disk full, etc.)
+- **FR-009**: Database MUST use standard SQLite format readable by any SQLite client (Python sqlite3, DBeaver, etc.)
+
+### Key Entities
+
+- **Database File**: A persistent SQLite database file containing parsed XER data; has a file path, creation timestamp, and source XER file reference
+- **Schema Information**: Metadata describing database structure; includes table names, column names, data types, and foreign key relationships
+- **Connection Info**: All information needed to connect to and query the database; includes file path, schema summary, and access instructions
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: Scripts can query loaded schedule data directly via SQL without MCP tool calls after initial load
+- **SC-002**: Database file is accessible and queryable by standard SQLite clients within 1 second of load completion
+- **SC-003**: Large schedules (10,000+ activities) can be queried directly by scripts in under 100ms per query
+- **SC-004**: Developers can write working SQL queries using only the schema information returned by the system
+- **SC-005**: 100% of data available through existing MCP tools is also available in the direct database
+
+## Assumptions
+
+- SQLite is an appropriate database format for this use case (widely supported, file-based, no server needed)
+- Scripts will primarily use Python, but any language with SQLite support should work
+- The database file will be stored in a project-relative or user-accessible directory
+- Single-user operation - concurrent writes from multiple sources are not required
+- Database persistence is session-based; the file may be cleaned up when the MCP server stops (or may persist based on configuration)
--- a/specs/002-direct-db-access/tasks.md
+++ b/specs/002-direct-db-access/tasks.md
@@ -0,0 +1,737 @@
+# Implementation Tasks: Direct Database Access for Scripts
+
+**Branch**: `002-direct-db-access` | **Spec**: [spec.md](./spec.md) | **Plan**: [plan.md](./plan.md)
+
+## Quick Reference
+
+- **Feature**: Direct Database Access for Scripts
+- **Version**: 0.2.0
+- **Test Command**: `pytest`
+- **Lint Command**: `ruff check .`
+
+---
+
+## Phase 1: Setup
+
+### Task 1.1: Create Feature Branch and Documentation Structure [X]
+
+**Type**: Setup
+**Why**: Establish isolated workspace for feature development
+
+**Steps**:
+1. Verify branch `002-direct-db-access` exists (already created during spec/plan)
+2. Verify all design artifacts exist:
+   - `specs/002-direct-db-access/spec.md`
+   - `specs/002-direct-db-access/plan.md`
+   - `specs/002-direct-db-access/research.md`
+   - `specs/002-direct-db-access/data-model.md`
+   - `specs/002-direct-db-access/contracts/mcp-tools.json`
+   - `specs/002-direct-db-access/quickstart.md`
+
+**Verification**: `git branch --show-current` shows `002-direct-db-access`
+
+**Acceptance**: All design artifacts present and branch is active
+
+---
+
+## Phase 2: Foundational - DatabaseManager Extension
+
+### Task 2.1: Add File-Based Database Support to DatabaseManager [X]
+
+**Type**: Implementation
+**Why**: Foundation for all persistent database features
+**Dependencies**: None
+
+**Contract Reference**: `contracts/mcp-tools.json` - DatabaseInfo schema
+
+**Test First** (TDD):
+```python
+# tests/unit/test_db_manager.py
+
+def test_initialize_with_memory_by_default():
+    """Default initialization uses in-memory database."""
+    dm = DatabaseManager()
+    dm.initialize()
+    assert dm.db_path == ":memory:"
+    assert dm.is_persistent is False
+
+def test_initialize_with_file_path():
+    """Can initialize with explicit file path."""
+    dm = DatabaseManager()
+    dm.initialize(db_path="/tmp/test.db")
+    assert dm.db_path == "/tmp/test.db"
+    assert dm.is_persistent is True
+    # Cleanup
+    os.unlink("/tmp/test.db")
+
+def test_initialize_with_empty_string_auto_generates_path():
+    """Empty string db_path with source_file auto-generates path."""
+    dm = DatabaseManager()
+    dm.initialize(db_path="", source_file="/path/to/schedule.xer")
+    assert dm.db_path == "/path/to/schedule.sqlite"
+    assert dm.is_persistent is True
+
+def test_file_database_persists_after_close():
+    """File-based database persists after connection close."""
+    dm = DatabaseManager()
+    dm.initialize(db_path="/tmp/persist_test.db")
+    # Insert test data would go here
+    dm.close()
+    assert os.path.exists("/tmp/persist_test.db")
+    # Cleanup
+    os.unlink("/tmp/persist_test.db")
+```
+
+**Implementation**:
+- Modify `src/xer_mcp/db/__init__.py`:
+  - Add `db_path` property to track current database path
+  - Add `is_persistent` property (True if file-based, False if in-memory)
+  - Add `source_file` property to track loaded XER file
+  - Add `loaded_at` property (datetime when data was loaded)
+  - Modify `initialize()` to accept optional `db_path` and `source_file` parameters
+  - If `db_path` is empty string and `source_file` provided, derive path from source file
+  - Use WAL mode for file-based databases: `PRAGMA journal_mode=WAL`
+
+**Files Changed**:
+- `src/xer_mcp/db/__init__.py`
+- `tests/unit/test_db_manager.py` (new)
+
+**Verification**: `pytest tests/unit/test_db_manager.py -v`
+
+**Acceptance**: All unit tests pass; DatabaseManager supports both in-memory and file-based modes
+
+---
+
+### Task 2.2: Implement Atomic Write Pattern [X]
+
+**Type**: Implementation
+**Why**: Prevents corrupted database files if process interrupted during load
+**Dependencies**: Task 2.1
+
+**Contract Reference**: `research.md` - Atomic Write Strategy
+
+**Test First** (TDD):
+```python
+# tests/unit/test_db_manager.py
+
+def test_atomic_write_creates_temp_file_first():
+    """Database is created at .tmp path first, then renamed."""
+    dm = DatabaseManager()
+    target = "/tmp/atomic_test.db"
+    # During initialization, temp file should exist
+    # After completion, only target should exist
+    dm.initialize(db_path=target)
+    assert os.path.exists(target)
+    assert not os.path.exists(target + ".tmp")
+    os.unlink(target)
+
+def test_atomic_write_removes_temp_on_failure():
+    """Temp file is cleaned up if initialization fails."""
+    # Test with invalid schema or similar failure scenario
+    pass
+```
+
+**Implementation**:
+- In `initialize()` method when `db_path` is not `:memory:`:
+  1. Create connection to `{db_path}.tmp`
+  2. Execute schema creation
+  3. Close connection
+  4. Rename `{db_path}.tmp` to `{db_path}` (atomic on POSIX)
+  5. Reopen connection to final path
+- Handle cleanup of `.tmp` file on failure
+
+**Files Changed**:
+- `src/xer_mcp/db/__init__.py`
+- `tests/unit/test_db_manager.py`
+
+**Verification**: `pytest tests/unit/test_db_manager.py -v`
+
+**Acceptance**: Atomic write tests pass; no partial database files created on failure
+
+---
+
+### Task 2.3: Add Schema Introspection Query [X]
+
+**Type**: Implementation
+**Why**: Required for returning schema information in responses
+**Dependencies**: Task 2.1
+
+**Contract Reference**: `contracts/mcp-tools.json` - SchemaInfo, TableInfo, ColumnInfo schemas
+
+**Test First** (TDD):
+```python
+# tests/unit/test_db_manager.py
+
+def test_get_schema_info_returns_all_tables():
+    """Schema info includes all database tables."""
+    dm = DatabaseManager()
+    dm.initialize()
+    schema = dm.get_schema_info()
+    assert schema["version"] == "0.2.0"
+    table_names = [t["name"] for t in schema["tables"]]
+    assert "projects" in table_names
+    assert "activities" in table_names
+    assert "relationships" in table_names
+    assert "wbs" in table_names
+    assert "calendars" in table_names
+
+def test_get_schema_info_includes_column_details():
+    """Schema info includes column names, types, and nullable."""
+    dm = DatabaseManager()
+    dm.initialize()
+    schema = dm.get_schema_info()
+    activities_table = next(t for t in schema["tables"] if t["name"] == "activities")
+    column_names = [c["name"] for c in activities_table["columns"]]
+    assert "task_id" in column_names
+    assert "task_name" in column_names
+    # Check column details
+    task_id_col = next(c for c in activities_table["columns"] if c["name"] == "task_id")
+    assert task_id_col["type"] == "TEXT"
+    assert task_id_col["nullable"] is False
+
+def test_get_schema_info_includes_row_counts():
+    """Schema info includes row counts for each table."""
+    dm = DatabaseManager()
+    dm.initialize()
+    schema = dm.get_schema_info()
+    for table in schema["tables"]:
+        assert "row_count" in table
+        assert isinstance(table["row_count"], int)
+```
+
+**Implementation**:
+- Add `get_schema_info()` method to DatabaseManager:
+  - Query `sqlite_master` for table names
+  - Use `PRAGMA table_info(table_name)` for column details
+  - Use `PRAGMA foreign_key_list(table_name)` for foreign keys
+  - Query `SELECT COUNT(*) FROM table` for row counts
+  - Return SchemaInfo structure matching contract
+
+**Files Changed**:
+- `src/xer_mcp/db/__init__.py`
+- `tests/unit/test_db_manager.py`
+
+**Verification**: `pytest tests/unit/test_db_manager.py -v`
+
+**Acceptance**: Schema introspection returns accurate table/column information
+
+---
+
+## Phase 3: User Story 1 - Load XER to Persistent Database (P1)
+
+### Task 3.1: Extend load_xer Tool with db_path Parameter [X]
+
+**Type**: Implementation
+**Why**: Core feature - enables persistent database creation
+**Dependencies**: Task 2.1, Task 2.2
+
+**Contract Reference**: `contracts/mcp-tools.json` - load_xer inputSchema
+
+**Test First** (TDD):
+```python
+# tests/contract/test_load_xer.py
+
+@pytest.mark.asyncio
+async def test_load_xer_with_db_path_creates_file(tmp_path, sample_xer_file):
+    """load_xer with db_path creates persistent database file."""
+    db_file = tmp_path / "schedule.db"
+    result = await load_xer(sample_xer_file, db_path=str(db_file))
+    assert result["success"] is True
+    assert db_file.exists()
+    assert result["database"]["db_path"] == str(db_file)
+    assert result["database"]["is_persistent"] is True
+
+@pytest.mark.asyncio
+async def test_load_xer_with_empty_db_path_auto_generates(sample_xer_file):
+    """load_xer with empty db_path generates path from XER filename."""
+    result = await load_xer(sample_xer_file, db_path="")
+    assert result["success"] is True
+    expected_db = sample_xer_file.replace(".xer", ".sqlite")
+    assert result["database"]["db_path"] == expected_db
+    assert result["database"]["is_persistent"] is True
+    # Cleanup
+    os.unlink(expected_db)
+
+@pytest.mark.asyncio
+async def test_load_xer_without_db_path_uses_memory(sample_xer_file):
+    """load_xer without db_path uses in-memory database (backward compatible)."""
+    result = await load_xer(sample_xer_file)
+    assert result["success"] is True
+    assert result["database"]["db_path"] == ":memory:"
+    assert result["database"]["is_persistent"] is False
+
+@pytest.mark.asyncio
+async def test_load_xer_database_contains_all_data(tmp_path, sample_xer_file):
+    """Persistent database contains all parsed data."""
+    db_file = tmp_path / "schedule.db"
+    result = await load_xer(sample_xer_file, db_path=str(db_file))
+
+    # Verify data via direct SQL
+    import sqlite3
+    conn = sqlite3.connect(str(db_file))
+    cursor = conn.execute("SELECT COUNT(*) FROM activities")
+    count = cursor.fetchone()[0]
+    conn.close()
+
+    assert count == result["activity_count"]
+```
+
+**Implementation**:
+- Modify `src/xer_mcp/tools/load_xer.py`:
+  - Add `db_path: str | None = None` parameter
+  - Pass `db_path` and `file_path` (as source_file) to `db.initialize()`
+  - Include `database` field in response with DatabaseInfo
+
+**Files Changed**:
+- `src/xer_mcp/tools/load_xer.py`
+- `tests/contract/test_load_xer.py`
+
+**Verification**: `pytest tests/contract/test_load_xer.py -v`
+
+**Acceptance**: load_xer creates persistent database when db_path provided
+
+---
+
+### Task 3.2: Add Database Info to load_xer Response [X]
+
+**Type**: Implementation
+**Why**: Response must include all info needed to connect to database
+**Dependencies**: Task 3.1, Task 2.3
+
+**Contract Reference**: `contracts/mcp-tools.json` - load_xer outputSchema.database
+
+**Test First** (TDD):
+```python
+# tests/contract/test_load_xer.py
+
+@pytest.mark.asyncio
+async def test_load_xer_response_includes_database_info(tmp_path, sample_xer_file):
+    """load_xer response includes complete database info."""
+    db_file = tmp_path / "schedule.db"
+    result = await load_xer(sample_xer_file, db_path=str(db_file))
+
+    assert "database" in result
+    db_info = result["database"]
+    assert "db_path" in db_info
+    assert "is_persistent" in db_info
+    assert "source_file" in db_info
+    assert "loaded_at" in db_info
+    assert "schema" in db_info
+
+@pytest.mark.asyncio
+async def test_load_xer_response_schema_includes_tables(tmp_path, sample_xer_file):
+    """load_xer response schema includes table information."""
+    db_file = tmp_path / "schedule.db"
+    result = await load_xer(sample_xer_file, db_path=str(db_file))
+
+    schema = result["database"]["schema"]
+    assert "version" in schema
+    assert "tables" in schema
+    table_names = [t["name"] for t in schema["tables"]]
+    assert "activities" in table_names
+    assert "relationships" in table_names
+```
+
+**Implementation**:
+- Modify `src/xer_mcp/tools/load_xer.py`:
+  - After successful load, call `db.get_schema_info()`
+  - Build DatabaseInfo response structure
+  - Include in return dictionary
+
+**Files Changed**:
+- `src/xer_mcp/tools/load_xer.py`
+- `tests/contract/test_load_xer.py`
+
+**Verification**: `pytest tests/contract/test_load_xer.py -v`
+
+**Acceptance**: load_xer response includes complete DatabaseInfo with schema
+
+---
+
+### Task 3.3: Register db_path Parameter with MCP Server [X]
+
+**Type**: Implementation
+**Why**: MCP server must expose the new parameter to clients
+**Dependencies**: Task 3.1
+
+**Contract Reference**: `contracts/mcp-tools.json` - load_xer inputSchema
+
+**Test First** (TDD):
+```python
+# tests/contract/test_load_xer.py
+
+def test_load_xer_tool_schema_includes_db_path():
+    """MCP tool schema includes db_path parameter."""
+    from xer_mcp.server import server
+    tools = server.list_tools()
+    load_xer_tool = next(t for t in tools if t.name == "load_xer")
+    props = load_xer_tool.inputSchema["properties"]
+    assert "db_path" in props
+    assert props["db_path"]["type"] == "string"
+```
+
+**Implementation**:
+- Modify MCP tool registration in `src/xer_mcp/server.py`:
+  - Add `db_path` to load_xer tool inputSchema
+  - Update tool handler to pass db_path to load_xer function
+
+**Files Changed**:
+- `src/xer_mcp/server.py`
+- `tests/contract/test_load_xer.py`
+
+**Verification**: `pytest tests/contract/test_load_xer.py -v`
+
+**Acceptance**: MCP server exposes db_path parameter for load_xer tool
+
+---
+
+### Task 3.4: Handle Database Write Errors [X]
+
+**Type**: Implementation
+**Why**: Clear error messages for write failures (FR-008)
+**Dependencies**: Task 3.1
+
+**Contract Reference**: `contracts/mcp-tools.json` - Error schema
+
+**Test First** (TDD):
+```python
+# tests/contract/test_load_xer.py
+
+@pytest.mark.asyncio
+async def test_load_xer_error_on_unwritable_path(sample_xer_file):
+    """load_xer returns error for unwritable path."""
+    result = await load_xer(sample_xer_file, db_path="/root/forbidden.db")
+    assert result["success"] is False
+    assert result["error"]["code"] == "FILE_NOT_WRITABLE"
+
+@pytest.mark.asyncio
+async def test_load_xer_error_on_invalid_path(sample_xer_file):
+    """load_xer returns error for invalid path."""
+    result = await load_xer(sample_xer_file, db_path="/nonexistent/dir/file.db")
+    assert result["success"] is False
+    assert result["error"]["code"] == "FILE_NOT_WRITABLE"
+```
+
+**Implementation**:
+- Add error handling in load_xer for database creation failures:
+  - Catch PermissionError → FILE_NOT_WRITABLE
+  - Catch OSError with ENOSPC → DISK_FULL
+  - Catch other sqlite3 errors → DATABASE_ERROR
+
+**Files Changed**:
+- `src/xer_mcp/tools/load_xer.py`
+- `src/xer_mcp/errors.py` (add new error classes if needed)
+- `tests/contract/test_load_xer.py`
+
+**Verification**: `pytest tests/contract/test_load_xer.py -v`
+
+**Acceptance**: Clear error messages returned for all database write failures
+
+---
+
+## Phase 4: User Story 2 - Retrieve Database Connection Information (P1)
+
+### Task 4.1: Create get_database_info Tool [X]
+
+**Type**: Implementation
+**Why**: Allows retrieval of database info without reloading
+**Dependencies**: Task 2.3
+
+**Contract Reference**: `contracts/mcp-tools.json` - get_database_info
+
+**Test First** (TDD):
+```python
+# tests/contract/test_get_database_info.py
+
+@pytest.mark.asyncio
+async def test_get_database_info_returns_current_database(tmp_path, sample_xer_file):
+    """get_database_info returns info about currently loaded database."""
+    db_file = tmp_path / "schedule.db"
+    await load_xer(sample_xer_file, db_path=str(db_file))
+
+    result = await get_database_info()
+    assert "database" in result
+    assert result["database"]["db_path"] == str(db_file)
+    assert result["database"]["is_persistent"] is True
+
+@pytest.mark.asyncio
+async def test_get_database_info_error_when_no_database():
+    """get_database_info returns error when no database loaded."""
+    # Reset database state
+    from xer_mcp.db import db
+    db.close()
+
+    result = await get_database_info()
+    assert "error" in result
+    assert result["error"]["code"] == "NO_FILE_LOADED"
+
+@pytest.mark.asyncio
+async def test_get_database_info_includes_schema(tmp_path, sample_xer_file):
+    """get_database_info includes schema information."""
+    db_file = tmp_path / "schedule.db"
+    await load_xer(sample_xer_file, db_path=str(db_file))
+
+    result = await get_database_info()
+    assert "schema" in result["database"]
+    assert "tables" in result["database"]["schema"]
+```
+
+**Implementation**:
+- Create `src/xer_mcp/tools/get_database_info.py`:
+  - Check if database is initialized
+  - Return NO_FILE_LOADED error if not
+  - Return DatabaseInfo structure with schema
+
+**Files Changed**:
+- `src/xer_mcp/tools/get_database_info.py` (new)
+- `tests/contract/test_get_database_info.py` (new)
+
+**Verification**: `pytest tests/contract/test_get_database_info.py -v`
+
+**Acceptance**: get_database_info returns complete DatabaseInfo or appropriate error
+
+---
+
+### Task 4.2: Register get_database_info with MCP Server [X]
+
+**Type**: Implementation
+**Why**: MCP server must expose the new tool to clients
+**Dependencies**: Task 4.1
+
+**Contract Reference**: `contracts/mcp-tools.json` - get_database_info
+
+**Test First** (TDD):
+```python
+# tests/contract/test_get_database_info.py
+
+def test_get_database_info_tool_registered():
+    """get_database_info tool is registered with MCP server."""
+    from xer_mcp.server import server
+    tools = server.list_tools()
+    tool_names = [t.name for t in tools]
+    assert "get_database_info" in tool_names
+```
+
+**Implementation**:
+- Modify `src/xer_mcp/server.py`:
+  - Import get_database_info function
+  - Add tool definition with empty inputSchema
+  - Add handler for get_database_info calls
+
+**Files Changed**:
+- `src/xer_mcp/server.py`
+- `tests/contract/test_get_database_info.py`
+
+**Verification**: `pytest tests/contract/test_get_database_info.py -v`
+
+**Acceptance**: get_database_info tool accessible via MCP
+
+---
+
+## Phase 5: User Story 3 - Query Database Schema Information (P2)
+
+### Task 5.1: Add Primary Key Information to Schema [X]
+
+**Type**: Implementation
+**Why**: Helps developers understand table structure for queries
+**Dependencies**: Task 2.3
+
+**Contract Reference**: `contracts/mcp-tools.json` - TableInfo.primary_key
+
+**Test First** (TDD):
+```python
+# tests/unit/test_db_manager.py
+
+def test_schema_info_includes_primary_keys():
+    """Schema info includes primary key for each table."""
+    dm = DatabaseManager()
+    dm.initialize()
+    schema = dm.get_schema_info()
+
+    activities_table = next(t for t in schema["tables"] if t["name"] == "activities")
+    assert "primary_key" in activities_table
+    assert "task_id" in activities_table["primary_key"]
+```
+
+**Implementation**:
+- Enhance `get_schema_info()` in DatabaseManager:
+  - Use `PRAGMA table_info()` to identify PRIMARY KEY columns
+  - Add to TableInfo structure
+
+**Files Changed**:
+- `src/xer_mcp/db/__init__.py`
+- `tests/unit/test_db_manager.py`
+
+**Verification**: `pytest tests/unit/test_db_manager.py -v`
+
+**Acceptance**: Primary key information included in schema response
+
+---
+
+### Task 5.2: Add Foreign Key Information to Schema [X]
+
+**Type**: Implementation
+**Why**: Documents table relationships for complex queries
+**Dependencies**: Task 5.1
+
+**Contract Reference**: `contracts/mcp-tools.json` - ForeignKeyInfo
+
+**Test First** (TDD):
+```python
+# tests/unit/test_db_manager.py
+
+def test_schema_info_includes_foreign_keys():
+    """Schema info includes foreign key relationships."""
+    dm = DatabaseManager()
+    dm.initialize()
+    schema = dm.get_schema_info()
+
+    activities_table = next(t for t in schema["tables"] if t["name"] == "activities")
+    assert "foreign_keys" in activities_table
+    # activities.proj_id -> projects.proj_id
+    fk = next((fk for fk in activities_table["foreign_keys"]
+               if fk["column"] == "proj_id"), None)
+    assert fk is not None
+    assert fk["references_table"] == "projects"
+    assert fk["references_column"] == "proj_id"
+```
+
+**Implementation**:
+- Enhance `get_schema_info()` in DatabaseManager:
+  - Use `PRAGMA foreign_key_list(table_name)` to get FK relationships
+  - Add to TableInfo structure
+
+**Files Changed**:
+- `src/xer_mcp/db/__init__.py`
+- `tests/unit/test_db_manager.py`
+
+**Verification**: `pytest tests/unit/test_db_manager.py -v`
+
+**Acceptance**: Foreign key information included in schema response
+
+---
+
+## Phase 6: Polish
+
+### Task 6.1: Integration Test - External Script Access [X]
+
+**Type**: Testing
+**Why**: Validates end-to-end workflow matches quickstart documentation
+**Dependencies**: All previous tasks
+
+**Contract Reference**: `quickstart.md` - Python Example
+
+**Test**:
+```python
+# tests/integration/test_direct_db_access.py
+
+@pytest.mark.asyncio
+async def test_external_script_can_query_database(tmp_path, sample_xer_file):
+    """External script can query database using returned path."""
+    db_file = tmp_path / "schedule.db"
+    result = await load_xer(sample_xer_file, db_path=str(db_file))
+
+    # Simulate external script access (as shown in quickstart.md)
+    import sqlite3
+    db_path = result["database"]["db_path"]
+
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+
+    # Query milestones
+    cursor = conn.execute("""
+        SELECT task_code, task_name, target_start_date, milestone_type
+        FROM activities
+        WHERE task_type IN ('TT_Mile', 'TT_FinMile')
+        ORDER BY target_start_date
+    """)
+
+    milestones = cursor.fetchall()
+    conn.close()
+
+    assert len(milestones) > 0
+    assert all(row["task_code"] for row in milestones)
+```
+
+**Files Changed**:
+- `tests/integration/test_direct_db_access.py` (new)
+
+**Verification**: `pytest tests/integration/test_direct_db_access.py -v`
+
+**Acceptance**: External script workflow matches quickstart documentation
+
+---
+
+### Task 6.2: Update Version to 0.2.0 [X]
+
+**Type**: Configuration
+**Why**: Semantic versioning for new feature release
+**Dependencies**: All previous tasks
+
+**Steps**:
+1. Update version in `pyproject.toml` to `0.2.0`
+2. Update version in schema introspection response to `0.2.0`
+3. Update any version references in documentation
+
+**Files Changed**:
+- `pyproject.toml`
+- `src/xer_mcp/db/__init__.py` (SCHEMA_VERSION constant)
+
+**Verification**: `grep -r "0.2.0" pyproject.toml src/`
+
+**Acceptance**: Version consistently shows 0.2.0 across project
+
+---
+
+### Task 6.3: Run Full Test Suite and Linting [X]
+
+**Type**: Verification
+**Why**: Ensure all tests pass and code meets standards
+**Dependencies**: All previous tasks
+
+**Steps**:
+1. Run `pytest` - all tests must pass
+2. Run `ruff check .` - no linting errors
+3. Run `ruff format --check .` - code properly formatted
+
+**Verification**:
+```bash
+pytest
+ruff check .
+ruff format --check .
+```
+
+**Acceptance**: All tests pass, no linting errors, code properly formatted
+
+---
+
+### Task 6.4: Commit and Prepare for Merge [X]
+
+**Type**: Git Operations
+**Why**: Prepare feature for merge to main branch
+**Dependencies**: Task 6.3
+
+**Steps**:
+1. Review all changes with `git diff main`
+2. Commit any uncommitted changes with descriptive messages
+3. Verify branch is ready for PR/merge
+
+**Verification**: `git status` shows clean working directory
+
+**Acceptance**: All changes committed, branch ready for merge
+
+---
+
+## Summary
+
+| Phase | Tasks | Focus |
+|-------|-------|-------|
+| Phase 1 | 1 | Setup and verification |
+| Phase 2 | 3 | DatabaseManager foundation |
+| Phase 3 | 4 | US1 - Load to persistent DB (P1) |
+| Phase 4 | 2 | US2 - Retrieve DB info (P1) |
+| Phase 5 | 2 | US3 - Schema information (P2) |
+| Phase 6 | 4 | Integration, versioning, polish |
+
+**Total Tasks**: 16
+**Estimated Test Count**: ~25 new tests
--- a/src/xer_mcp/db/init.py
+++ b/src/xer_mcp/db/init.py
@@ -1,24 +1,66 @@
 """Database connection management for XER MCP Server."""

+import os
 import sqlite3
 from collections.abc import Generator
 from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path

 from xer_mcp.db.schema import get_schema

+# Schema version for introspection responses
+SCHEMA_VERSION = "0.2.0"
+

 class DatabaseManager:
    """Manages SQLite database connections and schema initialization."""

    def __init__(self) -> None:
-        """Initialize database manager with in-memory database."""
+        """Initialize database manager."""
        self._connection: sqlite3.Connection | None = None
+        self._db_path: str = ":memory:"
+        self._source_file: str | None = None
+        self._loaded_at: datetime | None = None

-    def initialize(self) -> None:
-        """Initialize the in-memory database with schema."""
-        self._connection = sqlite3.connect(":memory:", check_same_thread=False)
-        self._connection.row_factory = sqlite3.Row
-        self._connection.executescript(get_schema())
+    def initialize(
+        self,
+        db_path: str | None = None,
+        source_file: str | None = None,
+    ) -> None:
+        """Initialize the database with schema.
+
+        Args:
+            db_path: Path for database file. If None or omitted, uses in-memory.
+                    If empty string, auto-generates from source_file.
+            source_file: Path to the XER file being loaded (for tracking).
+        """
+        self._source_file = source_file
+        self._loaded_at = datetime.now()
+
+        # Determine database path
+        if db_path is None:
+            # Default: in-memory database
+            self._db_path = ":memory:"
+        elif db_path == "":
+            # Auto-generate from source file
+            if source_file:
+                base = Path(source_file).with_suffix(".sqlite")
+                self._db_path = str(base)
+            else:
+                self._db_path = ":memory:"
+        else:
+            # Use provided path
+            self._db_path = db_path
+
+        # Create database
+        if self._db_path == ":memory:":
+            self._connection = sqlite3.connect(":memory:", check_same_thread=False)
+            self._connection.row_factory = sqlite3.Row
+            self._connection.executescript(get_schema())
+        else:
+            # File-based database with atomic write pattern
+            self._create_file_database()

    def clear(self) -> None:
        """Clear all data from the database."""
@@ -61,6 +103,159 @@ class DatabaseManager:
        """Check if the database is initialized."""
        return self._connection is not None

+    @property
+    def db_path(self) -> str:
+        """Get the database path."""
+        return self._db_path
+
+    @property
+    def is_persistent(self) -> bool:
+        """Check if the database is file-based (persistent)."""
+        return self._db_path != ":memory:"
+
+    @property
+    def source_file(self) -> str | None:
+        """Get the source XER file path."""
+        return self._source_file
+
+    @property
+    def loaded_at(self) -> datetime | None:
+        """Get the timestamp when data was loaded."""
+        return self._loaded_at
+
+    def _create_file_database(self) -> None:
+        """Create a file-based database with atomic write pattern."""
+        temp_path = self._db_path + ".tmp"
+
+        try:
+            # Create database at temp path
+            conn = sqlite3.connect(temp_path, check_same_thread=False)
+            conn.row_factory = sqlite3.Row
+            conn.executescript(get_schema())
+            conn.commit()
+            conn.close()
+
+            # Atomic rename (POSIX)
+            if os.path.exists(self._db_path):
+                os.unlink(self._db_path)
+            os.rename(temp_path, self._db_path)
+
+            # Open final database with WAL mode
+            self._connection = sqlite3.connect(self._db_path, check_same_thread=False)
+            self._connection.row_factory = sqlite3.Row
+            self._connection.execute("PRAGMA journal_mode=WAL")
+        except Exception:
+            # Clean up temp file on failure
+            if os.path.exists(temp_path):
+                os.unlink(temp_path)
+            raise
+
+    def get_schema_info(self) -> dict:
+        """Get database schema information for introspection.
+
+        Returns:
+            Dictionary with schema version and table information.
+        """
+        if self._connection is None:
+            raise RuntimeError("Database not initialized. Call initialize() first.")
+
+        tables = []
+
+        # Get all tables (excluding sqlite internal tables)
+        cursor = self._connection.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' "
+            "AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        )
+        table_names = [row[0] for row in cursor.fetchall()]
+
+        for table_name in table_names:
+            table_info = self._get_table_info(table_name)
+            tables.append(table_info)
+
+        return {
+            "version": SCHEMA_VERSION,
+            "tables": tables,
+        }
+
+    def _get_table_info(self, table_name: str) -> dict:
+        """Get detailed information about a table.
+
+        Args:
+            table_name: Name of the table.
+
+        Returns:
+            Dictionary with table name, columns, primary keys, foreign keys, row count.
+        """
+        columns = []
+        primary_key = []
+
+        # Get column info
+        cursor = self._connection.execute(f"PRAGMA table_info({table_name})")  # noqa: S608
+        for row in cursor.fetchall():
+            col_name = row[1]
+            col_type = row[2] or "TEXT"
+            not_null = bool(row[3])
+            default_val = row[4]
+            is_pk = bool(row[5])
+
+            col_info: dict = {
+                "name": col_name,
+                "type": col_type,
+                "nullable": not not_null,
+            }
+            if default_val is not None:
+                col_info["default"] = str(default_val)
+
+            columns.append(col_info)
+
+            if is_pk:
+                primary_key.append(col_name)
+
+        # Get foreign keys
+        foreign_keys = []
+        cursor = self._connection.execute(
+            f"PRAGMA foreign_key_list({table_name})"  # noqa: S608
+        )
+        for row in cursor.fetchall():
+            fk_info = {
+                "column": row[3],  # from column
+                "references_table": row[2],  # table
+                "references_column": row[4],  # to column
+            }
+            foreign_keys.append(fk_info)
+
+        # Get row count
+        cursor = self._connection.execute(
+            f"SELECT COUNT(*) FROM {table_name}"  # noqa: S608
+        )
+        row_count = cursor.fetchone()[0]
+
+        return {
+            "name": table_name,
+            "columns": columns,
+            "primary_key": primary_key,
+            "foreign_keys": foreign_keys,
+            "row_count": row_count,
+        }
+
+    def get_database_info(self) -> dict:
+        """Get complete database information for API responses.
+
+        Returns:
+            Dictionary with database path, persistence status, source file,
+            loaded timestamp, and schema information.
+        """
+        if not self.is_initialized:
+            raise RuntimeError("Database not initialized. Call initialize() first.")
+
+        return {
+            "db_path": self._db_path,
+            "is_persistent": self.is_persistent,
+            "source_file": self._source_file,
+            "loaded_at": self._loaded_at.isoformat() if self._loaded_at else None,
+            "schema": self.get_schema_info(),
+        }
+

 # Global database manager instance
 db = DatabaseManager()
--- a/src/xer_mcp/db/loader.py
+++ b/src/xer_mcp/db/loader.py
@@ -78,9 +78,9 @@ def load_parsed_data(parsed: ParsedXer, project_id: str) -> None:
                        task_id, proj_id, wbs_id, task_code, task_name, task_type,
                        target_start_date, target_end_date, early_start_date, early_end_date,
                        act_start_date, act_end_date,
-                        total_float_hr_cnt, driving_path_flag, status_code
+                        total_float_hr_cnt, driving_path_flag, status_code, milestone_type
                    )
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                    """,
                    (
                        task["task_id"],
@@ -98,6 +98,7 @@ def load_parsed_data(parsed: ParsedXer, project_id: str) -> None:
                        task["total_float_hr_cnt"],
                        1 if task["driving_path_flag"] else 0,
                        task["status_code"],
+                        task.get("milestone_type"),
                    ),
                )

--- a/src/xer_mcp/db/queries.py
+++ b/src/xer_mcp/db/queries.py
@@ -239,16 +239,18 @@ def query_relationships(
            lag_hours=row[6] or 0.0,
            pred_type=pred_type,
        )
-        relationships.append({
-            "task_pred_id": row[0],
-            "task_id": row[1],
-            "task_name": row[2],
-            "pred_task_id": row[3],
-            "pred_task_name": row[4],
-            "pred_type": pred_type,
-            "lag_hr_cnt": row[6],
-            "driving": driving,
-        })
+        relationships.append(
+            {
+                "task_pred_id": row[0],
+                "task_id": row[1],
+                "task_name": row[2],
+                "pred_task_id": row[3],
+                "pred_task_name": row[4],
+                "pred_type": pred_type,
+                "lag_hr_cnt": row[6],
+                "driving": driving,
+            }
+        )

    return relationships, total

@@ -298,14 +300,16 @@ def get_predecessors(activity_id: str) -> list[dict]:
            lag_hours=row[4] or 0.0,
            pred_type=pred_type,
        )
-        result.append({
-            "task_id": row[0],
-            "task_code": row[1],
-            "task_name": row[2],
-            "relationship_type": pred_type,
-            "lag_hr_cnt": row[4],
-            "driving": driving,
-        })
+        result.append(
+            {
+                "task_id": row[0],
+                "task_code": row[1],
+                "task_name": row[2],
+                "relationship_type": pred_type,
+                "lag_hr_cnt": row[4],
+                "driving": driving,
+            }
+        )

    return result

@@ -355,14 +359,16 @@ def get_successors(activity_id: str) -> list[dict]:
            lag_hours=row[4] or 0.0,
            pred_type=pred_type,
        )
-        result.append({
-            "task_id": row[0],
-            "task_code": row[1],
-            "task_name": row[2],
-            "relationship_type": pred_type,
-            "lag_hr_cnt": row[4],
-            "driving": driving,
-        })
+        result.append(
+            {
+                "task_id": row[0],
+                "task_code": row[1],
+                "task_name": row[2],
+                "relationship_type": pred_type,
+                "lag_hr_cnt": row[4],
+                "driving": driving,
+            }
+        )

    return result

@@ -396,9 +402,9 @@ def get_project_summary(project_id: str) -> dict | None:
        cur.execute("SELECT COUNT(*) FROM activities")
        activity_count = cur.fetchone()[0]

-    # Get milestone count
+    # Get milestone count (both start and finish milestones)
    with db.cursor() as cur:
-        cur.execute("SELECT COUNT(*) FROM activities WHERE task_type = 'TT_Mile'")
+        cur.execute("SELECT COUNT(*) FROM activities WHERE task_type IN ('TT_Mile', 'TT_FinMile')")
        milestone_count = cur.fetchone()[0]

    # Get critical activity count
@@ -419,16 +425,16 @@ def get_project_summary(project_id: str) -> dict | None:


 def query_milestones() -> list[dict]:
-    """Query all milestone activities.
+    """Query all milestone activities (both start and finish milestones).

    Returns:
-        List of milestone activity dicts
+        List of milestone activity dicts with milestone_type (start/finish)
    """
    query = """
        SELECT task_id, task_code, task_name,
-               target_start_date, target_end_date, status_code
+               target_start_date, target_end_date, status_code, milestone_type
        FROM activities
-        WHERE task_type = 'TT_Mile'
+        WHERE task_type IN ('TT_Mile', 'TT_FinMile')
        ORDER BY target_start_date, task_code
    """

@@ -444,6 +450,7 @@ def query_milestones() -> list[dict]:
            "target_start_date": row[3],
            "target_end_date": row[4],
            "status_code": row[5],
+            "milestone_type": row[6],
        }
        for row in rows
    ]
--- a/src/xer_mcp/db/schema.py
+++ b/src/xer_mcp/db/schema.py
@@ -28,6 +28,7 @@ CREATE TABLE IF NOT EXISTS activities (
    total_float_hr_cnt REAL,
    driving_path_flag INTEGER DEFAULT 0,
    status_code TEXT,
+    milestone_type TEXT,
    FOREIGN KEY (proj_id) REFERENCES projects(proj_id)
 );

--- a/src/xer_mcp/errors.py
+++ b/src/xer_mcp/errors.py
@@ -56,3 +56,30 @@ class ActivityNotFoundError(XerMcpError):
            "ACTIVITY_NOT_FOUND",
            f"Activity not found: {activity_id}",
        )
+
+
+class FileNotWritableError(XerMcpError):
+    """Raised when the database file path is not writable."""
+
+    def __init__(self, path: str, reason: str = "") -> None:
+        msg = f"Cannot write to database file: {path}"
+        if reason:
+            msg = f"{msg} ({reason})"
+        super().__init__("FILE_NOT_WRITABLE", msg)
+
+
+class DiskFullError(XerMcpError):
+    """Raised when there is insufficient disk space."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(
+            "DISK_FULL",
+            f"Insufficient disk space to create database: {path}",
+        )
+
+
+class DatabaseError(XerMcpError):
+    """Raised for general database errors."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__("DATABASE_ERROR", message)
--- a/src/xer_mcp/parser/table_handlers/task.py
+++ b/src/xer_mcp/parser/table_handlers/task.py
@@ -26,6 +26,22 @@ class TaskHandler(TableHandler):
        float_str = data.get("total_float_hr_cnt", "")
        total_float = float(float_str) if float_str else None

+        # Parse milestone_type
+        # First check explicit milestone_type field (MS_Start -> 'start', MS_Finish -> 'finish')
+        # Then derive from task_type (TT_Mile -> 'start', TT_FinMile -> 'finish')
+        raw_milestone_type = data.get("milestone_type", "")
+        task_type = data.get("task_type", "")
+        milestone_type = None
+        if raw_milestone_type:
+            if raw_milestone_type == "MS_Start":
+                milestone_type = "start"
+            elif raw_milestone_type == "MS_Finish":
+                milestone_type = "finish"
+        elif task_type == "TT_Mile":
+            milestone_type = "start"
+        elif task_type == "TT_FinMile":
+            milestone_type = "finish"
+
        return {
            "task_id": data.get("task_id", ""),
            "proj_id": data.get("proj_id", ""),
@@ -42,4 +58,5 @@ class TaskHandler(TableHandler):
            "act_end_date": convert_date(data.get("act_end_date")),
            "total_float_hr_cnt": total_float,
            "driving_path_flag": driving_path,
+            "milestone_type": milestone_type,
        }
--- a/src/xer_mcp/server.py
+++ b/src/xer_mcp/server.py
@@ -50,6 +50,12 @@ async def list_tools() -> list[Tool]:
                        "type": "string",
                        "description": "Project ID to select (required for multi-project files)",
                    },
+                    "db_path": {
+                        "type": "string",
+                        "description": "Path for persistent SQLite database file. "
+                        "If omitted, uses in-memory database. "
+                        "If empty string, auto-generates path from XER filename (same directory, .sqlite extension).",
+                    },
                },
                "required": ["file_path"],
            },
@@ -183,6 +189,15 @@ async def list_tools() -> list[Tool]:
                "properties": {},
            },
        ),
+        Tool(
+            name="get_database_info",
+            description="Get information about the currently loaded database including file path and schema. "
+            "Use this to get connection details for direct SQL access.",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        ),
    ]


@@ -197,6 +212,7 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
        result = await load_xer(
            file_path=arguments["file_path"],
            project_id=arguments.get("project_id"),
+            db_path=arguments.get("db_path"),
        )
        return [TextContent(type="text", text=json.dumps(result, indent=2))]

@@ -258,6 +274,12 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
        result = await get_critical_path()
        return [TextContent(type="text", text=json.dumps(result, indent=2))]

+    if name == "get_database_info":
+        from xer_mcp.tools.get_database_info import get_database_info
+
+        result = await get_database_info()
+        return [TextContent(type="text", text=json.dumps(result, indent=2))]
+
    raise ValueError(f"Unknown tool: {name}")


--- a/src/xer_mcp/tools/get_database_info.py
+++ b/src/xer_mcp/tools/get_database_info.py
@@ -0,0 +1,25 @@
+"""get_database_info MCP tool implementation."""
+
+from xer_mcp.db import db
+
+
+async def get_database_info() -> dict:
+    """Get information about the currently loaded database.
+
+    Returns connection details for direct SQL access including
+    database path, schema information, and metadata.
+
+    Returns:
+        Dictionary with database info or error if no database loaded
+    """
+    if not db.is_initialized:
+        return {
+            "error": {
+                "code": "NO_FILE_LOADED",
+                "message": "No XER file is loaded. Use the load_xer tool first.",
+            }
+        }
+
+    return {
+        "database": db.get_database_info(),
+    }
--- a/src/xer_mcp/tools/list_milestones.py
+++ b/src/xer_mcp/tools/list_milestones.py
@@ -7,6 +7,8 @@ from xer_mcp.server import is_file_loaded
 async def list_milestones() -> dict:
    """List all milestone activities in the loaded project.

+    Returns both Start Milestones and Finish Milestones with their milestone_type.
+
    Returns:
        Dictionary with list of milestones, each containing:
        - task_id: Activity ID
@@ -15,6 +17,7 @@ async def list_milestones() -> dict:
        - target_start_date: Target start date
        - target_end_date: Target end date
        - status_code: Activity status
+        - milestone_type: 'start' for start milestones, 'finish' for finish milestones
    """
    if not is_file_loaded():
        return {
--- a/src/xer_mcp/tools/load_xer.py
+++ b/src/xer_mcp/tools/load_xer.py
@@ -1,5 +1,9 @@
 """load_xer MCP tool implementation."""

+import errno
+import os
+import sqlite3
+
 from xer_mcp.db import db
 from xer_mcp.db.loader import get_activity_count, get_relationship_count, load_parsed_data
 from xer_mcp.errors import FileNotFoundError, ParseError
@@ -7,19 +11,55 @@ from xer_mcp.parser.xer_parser import XerParser
 from xer_mcp.server import set_file_loaded


-async def load_xer(file_path: str, project_id: str | None = None) -> dict:
+async def load_xer(
+    file_path: str,
+    project_id: str | None = None,
+    db_path: str | None = None,
+) -> dict:
    """Load a Primavera P6 XER file and parse its schedule data.

    Args:
        file_path: Absolute path to the XER file
        project_id: Project ID to select (required for multi-project files)
+        db_path: Path for persistent database file. If None, uses in-memory.
+                If empty string, auto-generates from XER filename.

    Returns:
        Dictionary with success status and project info or error details
    """
-    # Ensure database is initialized
-    if not db.is_initialized:
-        db.initialize()
+    # Initialize database with specified path
+    try:
+        db.initialize(db_path=db_path, source_file=file_path)
+    except PermissionError:
+        target = db_path if db_path else file_path
+        return {
+            "success": False,
+            "error": {"code": "FILE_NOT_WRITABLE", "message": f"Cannot write database: {target}"},
+        }
+    except OSError as e:
+        target = db_path if db_path else file_path
+        if e.errno == errno.ENOSPC:
+            return {
+                "success": False,
+                "error": {"code": "DISK_FULL", "message": f"Insufficient disk space: {target}"},
+            }
+        if e.errno == errno.ENOENT:
+            return {
+                "success": False,
+                "error": {
+                    "code": "FILE_NOT_WRITABLE",
+                    "message": f"Directory does not exist: {os.path.dirname(target)}",
+                },
+            }
+        return {
+            "success": False,
+            "error": {"code": "DATABASE_ERROR", "message": str(e)},
+        }
+    except sqlite3.Error as e:
+        return {
+            "success": False,
+            "error": {"code": "DATABASE_ERROR", "message": str(e)},
+        }

    parser = XerParser()

@@ -73,6 +113,9 @@ async def load_xer(file_path: str, project_id: str | None = None) -> dict:
    activity_count = get_activity_count()
    relationship_count = get_relationship_count()

+    # Get database info
+    database_info = db.get_database_info()
+
    return {
        "success": True,
        "project": {
@@ -83,4 +126,5 @@ async def load_xer(file_path: str, project_id: str | None = None) -> dict:
        },
        "activity_count": activity_count,
        "relationship_count": relationship_count,
+        "database": database_info,
    }
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -19,12 +19,12 @@ ERMHDR\t21.12\t2026-01-06\tProject\tADMIN\ttestuser\tdbTest\tProject Management\
 %R\t101\t1001\t\t1\t1\tN\tN\tWS_Open\tPH1\tPhase 1\t\t100\t6\t0.88\t0.0000\t0.0000\t\t\t\t\t\tEC_Cmp_pct\tEE_Rem_hr\twbs-guid-2\t\t
 %R\t102\t1001\t\t2\t1\tN\tN\tWS_Open\tPH2\tPhase 2\t\t100\t6\t0.88\t0.0000\t0.0000\t\t\t\t\t\tEC_Cmp_pct\tEE_Rem_hr\twbs-guid-3\t\t
 %T\tTASK
-%F\ttask_id\tproj_id\twbs_id\tclndr_id\tphys_complete_pct\trev_fdbk_flag\test_wt\tlock_plan_flag\tauto_compute_act_flag\tcomplete_pct_type\ttask_type\tduration_type\tstatus_code\ttask_code\ttask_name\trsrc_id\ttotal_float_hr_cnt\tfree_float_hr_cnt\tremain_drtn_hr_cnt\tact_work_qty\tremain_work_qty\ttarget_work_qty\ttarget_drtn_hr_cnt\ttarget_equip_qty\tact_equip_qty\tremain_equip_qty\tcstr_date\tact_start_date\tact_end_date\tlate_start_date\tlate_end_date\texpect_end_date\tearly_start_date\tearly_end_date\trestart_date\treend_date\ttarget_start_date\ttarget_end_date\trem_late_start_date\trem_late_end_date\tcstr_type\tpriority_type\tsuspend_date\tresume_date\tfloat_path\tfloat_path_order\tguid\ttmpl_guid\tcstr_date2\tcstr_type2\tdriving_path_flag\tact_this_per_work_qty\tact_this_per_equip_qty\texternal_early_start_date\texternal_late_end_date\tcreate_date\tupdate_date\tcreate_user\tupdate_user\tlocation_id\tcrt_path_num
-%R\t2001\t1001\t101\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Mile\tDT_FixedDrtn\tTK_NotStart\tA1000\tProject Start\t\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t\t\t\t2026-01-01 07:00\t2026-01-01 07:00\t\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t\tPT_Normal\t\t\t1\t1\ttask-guid-1\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t
-%R\t2002\t1001\t101\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Task\tDT_FixedDUR2\tTK_NotStart\tA1010\tSite Preparation\t\t0\t0\t40\t0\t0\t0\t40\t0\t0\t0\t\t\t\t2026-01-02 07:00\t2026-01-08 15:00\t\t2026-01-02 07:00\t2026-01-08 15:00\t2026-01-02 07:00\t2026-01-08 15:00\t2026-01-02 07:00\t2026-01-08 15:00\t2026-01-02 07:00\t2026-01-08 15:00\t\tPT_Normal\t\t\t1\t2\ttask-guid-2\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t
-%R\t2003\t1001\t101\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Task\tDT_FixedDUR2\tTK_NotStart\tA1020\tFoundation Work\t\t80\t0\t80\t0\t0\t0\t80\t0\t0\t0\t\t\t\t2026-01-09 07:00\t2026-01-22 15:00\t\t2026-01-09 07:00\t2026-01-22 15:00\t2026-01-09 07:00\t2026-01-22 15:00\t2026-01-09 07:00\t2026-01-22 15:00\t2026-01-09 07:00\t2026-01-22 15:00\t\tPT_Normal\t\t\t1\t3\ttask-guid-3\t\t\t\tN\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t
-%R\t2004\t1001\t102\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Task\tDT_FixedDUR2\tTK_NotStart\tA1030\tStructural Work\t\t0\t0\t160\t0\t0\t0\t160\t0\t0\t0\t\t\t\t2026-01-23 07:00\t2026-02-19 15:00\t\t2026-01-23 07:00\t2026-02-19 15:00\t2026-01-23 07:00\t2026-02-19 15:00\t2026-01-23 07:00\t2026-02-19 15:00\t2026-01-23 07:00\t2026-02-19 15:00\t\tPT_Normal\t\t\t1\t4\ttask-guid-4\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t
-%R\t2005\t1001\t102\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Mile\tDT_FixedDrtn\tTK_NotStart\tA1040\tProject Complete\t\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t\t\t\t2026-02-20 07:00\t2026-02-20 07:00\t\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t\tPT_Normal\t\t\t1\t5\ttask-guid-5\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t
+%F\ttask_id\tproj_id\twbs_id\tclndr_id\tphys_complete_pct\trev_fdbk_flag\test_wt\tlock_plan_flag\tauto_compute_act_flag\tcomplete_pct_type\ttask_type\tduration_type\tstatus_code\ttask_code\ttask_name\trsrc_id\ttotal_float_hr_cnt\tfree_float_hr_cnt\tremain_drtn_hr_cnt\tact_work_qty\tremain_work_qty\ttarget_work_qty\ttarget_drtn_hr_cnt\ttarget_equip_qty\tact_equip_qty\tremain_equip_qty\tcstr_date\tact_start_date\tact_end_date\tlate_start_date\tlate_end_date\texpect_end_date\tearly_start_date\tearly_end_date\trestart_date\treend_date\ttarget_start_date\ttarget_end_date\trem_late_start_date\trem_late_end_date\tcstr_type\tpriority_type\tsuspend_date\tresume_date\tfloat_path\tfloat_path_order\tguid\ttmpl_guid\tcstr_date2\tcstr_type2\tdriving_path_flag\tact_this_per_work_qty\tact_this_per_equip_qty\texternal_early_start_date\texternal_late_end_date\tcreate_date\tupdate_date\tcreate_user\tupdate_user\tlocation_id\tcrt_path_num\tmilestone_type
+%R\t2001\t1001\t101\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Mile\tDT_FixedDrtn\tTK_NotStart\tA1000\tProject Start\t\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t\t\t\t2026-01-01 07:00\t2026-01-01 07:00\t\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t2026-01-01 07:00\t\tPT_Normal\t\t\t1\t1\ttask-guid-1\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t\tMS_Start
+%R\t2002\t1001\t101\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Task\tDT_FixedDUR2\tTK_NotStart\tA1010\tSite Preparation\t\t0\t0\t40\t0\t0\t0\t40\t0\t0\t0\t\t\t\t2026-01-02 07:00\t2026-01-08 15:00\t\t2026-01-02 07:00\t2026-01-08 15:00\t2026-01-02 07:00\t2026-01-08 15:00\t2026-01-02 07:00\t2026-01-08 15:00\t2026-01-02 07:00\t2026-01-08 15:00\t\tPT_Normal\t\t\t1\t2\ttask-guid-2\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t\t
+%R\t2003\t1001\t101\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Task\tDT_FixedDUR2\tTK_NotStart\tA1020\tFoundation Work\t\t80\t0\t80\t0\t0\t0\t80\t0\t0\t0\t\t\t\t2026-01-09 07:00\t2026-01-22 15:00\t\t2026-01-09 07:00\t2026-01-22 15:00\t2026-01-09 07:00\t2026-01-22 15:00\t2026-01-09 07:00\t2026-01-22 15:00\t2026-01-09 07:00\t2026-01-22 15:00\t\tPT_Normal\t\t\t1\t3\ttask-guid-3\t\t\t\tN\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t\t
+%R\t2004\t1001\t102\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Task\tDT_FixedDUR2\tTK_NotStart\tA1030\tStructural Work\t\t0\t0\t160\t0\t0\t0\t160\t0\t0\t0\t\t\t\t2026-01-23 07:00\t2026-02-19 15:00\t\t2026-01-23 07:00\t2026-02-19 15:00\t2026-01-23 07:00\t2026-02-19 15:00\t2026-01-23 07:00\t2026-02-19 15:00\t2026-01-23 07:00\t2026-02-19 15:00\t\tPT_Normal\t\t\t1\t4\ttask-guid-4\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t\t
+%R\t2005\t1001\t102\t1\t0\tN\t1\tN\tN\tCP_Drtn\tTT_Mile\tDT_FixedDrtn\tTK_NotStart\tA1040\tProject Complete\t\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t\t\t\t2026-02-20 07:00\t2026-02-20 07:00\t\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t2026-02-20 07:00\t\tPT_Normal\t\t\t1\t5\ttask-guid-5\t\t\t\tY\t0\t0\t\t\t2026-01-06 00:00\t2026-01-06 00:00\tADMIN\tADMIN\t\t\tMS_Finish
 %T\tTASKPRED
 %F\ttask_pred_id\ttask_id\tpred_task_id\tproj_id\tpred_proj_id\tpred_type\tlag_hr_cnt\tcomments\tfloat_path\taref\tarls
 %R\t3001\t2002\t2001\t1001\t1001\tPR_FS\t0\t\t\t2026-01-01 07:00\t2026-01-02 07:00
--- a/tests/contract/test_get_database_info.py
+++ b/tests/contract/test_get_database_info.py
@@ -0,0 +1,143 @@
+"""Contract tests for get_database_info MCP tool."""
+
+from pathlib import Path
+
+import pytest
+
+from xer_mcp.db import db
+
+
+@pytest.fixture(autouse=True)
+def setup_db():
+    """Reset database state for each test."""
+    if db.is_initialized:
+        db.close()
+    yield
+    if db.is_initialized:
+        db.close()
+
+
+class TestGetDatabaseInfoContract:
+    """Contract tests verifying get_database_info tool interface."""
+
+    async def test_get_database_info_returns_current_database(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """get_database_info returns info about currently loaded database."""
+        from xer_mcp.tools.get_database_info import get_database_info
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        result = await get_database_info()
+
+        assert "database" in result
+        assert result["database"]["db_path"] == str(db_file)
+        assert result["database"]["is_persistent"] is True
+
+    async def test_get_database_info_error_when_no_database(self) -> None:
+        """get_database_info returns error when no database loaded."""
+        from xer_mcp.tools.get_database_info import get_database_info
+
+        # Ensure database is not initialized
+        if db.is_initialized:
+            db.close()
+
+        result = await get_database_info()
+
+        assert "error" in result
+        assert result["error"]["code"] == "NO_FILE_LOADED"
+
+    async def test_get_database_info_includes_schema(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """get_database_info includes schema information."""
+        from xer_mcp.tools.get_database_info import get_database_info
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        result = await get_database_info()
+
+        assert "schema" in result["database"]
+        assert "tables" in result["database"]["schema"]
+
+    async def test_get_database_info_includes_loaded_at(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """get_database_info includes loaded_at timestamp."""
+        from xer_mcp.tools.get_database_info import get_database_info
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        result = await get_database_info()
+
+        assert "loaded_at" in result["database"]
+        # Should be ISO format timestamp
+        assert "T" in result["database"]["loaded_at"]
+
+    async def test_get_database_info_includes_source_file(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """get_database_info includes source XER file path."""
+        from xer_mcp.tools.get_database_info import get_database_info
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        result = await get_database_info()
+
+        assert result["database"]["source_file"] == str(sample_xer_single_project)
+
+    async def test_get_database_info_for_memory_database(
+        self, sample_xer_single_project: Path
+    ) -> None:
+        """get_database_info works for in-memory database."""
+        from xer_mcp.tools.get_database_info import get_database_info
+        from xer_mcp.tools.load_xer import load_xer
+
+        await load_xer(file_path=str(sample_xer_single_project))
+
+        result = await get_database_info()
+
+        assert "database" in result
+        assert result["database"]["db_path"] == ":memory:"
+        assert result["database"]["is_persistent"] is False
+
+
+class TestGetDatabaseInfoToolSchema:
+    """Tests for MCP tool schema."""
+
+    async def test_get_database_info_tool_registered(self) -> None:
+        """get_database_info tool is registered with MCP server."""
+        from xer_mcp.server import list_tools
+
+        tools = await list_tools()
+        tool_names = [t.name for t in tools]
+        assert "get_database_info" in tool_names
+
+    async def test_get_database_info_tool_has_empty_input_schema(self) -> None:
+        """get_database_info tool has no required inputs."""
+        from xer_mcp.server import list_tools
+
+        tools = await list_tools()
+        tool = next(t for t in tools if t.name == "get_database_info")
+        # Should have empty or no required properties
+        assert "required" not in tool.inputSchema or len(tool.inputSchema.get("required", [])) == 0
--- a/tests/contract/test_list_milestones.py
+++ b/tests/contract/test_list_milestones.py
@@ -87,3 +87,38 @@ class TestListMilestonesContract:

        assert "error" in result
        assert result["error"]["code"] == "NO_FILE_LOADED"
+
+    async def test_list_milestones_includes_milestone_type_field(
+        self, sample_xer_single_project: Path
+    ) -> None:
+        """list_milestones returns milestones with milestone_type field."""
+        from xer_mcp.tools.list_milestones import list_milestones
+        from xer_mcp.tools.load_xer import load_xer
+
+        await load_xer(file_path=str(sample_xer_single_project))
+
+        result = await list_milestones()
+
+        # All milestones should have milestone_type field
+        for milestone in result["milestones"]:
+            assert "milestone_type" in milestone
+
+    async def test_list_milestones_returns_start_and_finish_types(
+        self, sample_xer_single_project: Path
+    ) -> None:
+        """list_milestones returns milestones with correct start/finish types."""
+        from xer_mcp.tools.list_milestones import list_milestones
+        from xer_mcp.tools.load_xer import load_xer
+
+        await load_xer(file_path=str(sample_xer_single_project))
+
+        result = await list_milestones()
+
+        # Find milestones by name and verify their types
+        milestones_by_name = {m["task_name"]: m for m in result["milestones"]}
+
+        # "Project Start" should be a start milestone
+        assert milestones_by_name["Project Start"]["milestone_type"] == "start"
+
+        # "Project Complete" should be a finish milestone
+        assert milestones_by_name["Project Complete"]["milestone_type"] == "finish"
--- a/tests/contract/test_load_xer.py
+++ b/tests/contract/test_load_xer.py
@@ -1,5 +1,6 @@
 """Contract tests for load_xer MCP tool."""

+import sqlite3
 from pathlib import Path

 import pytest
@@ -9,10 +10,14 @@ from xer_mcp.db import db

@pytest.fixture(autouse=True)
 def setup_db():
-    """Initialize and clear database for each test."""
-    db.initialize()
+    """Reset database state for each test."""
+    # Close any existing connection
+    if db.is_initialized:
+        db.close()
    yield
-    db.clear()
+    # Cleanup after test
+    if db.is_initialized:
+        db.close()


 class TestLoadXerContract:
@@ -105,3 +110,141 @@ class TestLoadXerContract:
        assert "plan_end_date" in result["project"]
        # Dates should be ISO8601 format
        assert "T" in result["project"]["plan_start_date"]
+
+
+class TestLoadXerPersistentDatabase:
+    """Contract tests for persistent database functionality."""
+
+    async def test_load_xer_with_db_path_creates_file(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """load_xer with db_path creates persistent database file."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        assert result["success"] is True
+        assert db_file.exists()
+        assert result["database"]["db_path"] == str(db_file)
+        assert result["database"]["is_persistent"] is True
+
+    async def test_load_xer_with_empty_db_path_auto_generates(self, tmp_path: Path) -> None:
+        """load_xer with empty db_path generates path from XER filename."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        # Create XER file in tmp_path
+        xer_file = tmp_path / "my_schedule.xer"
+        from tests.conftest import SAMPLE_XER_SINGLE_PROJECT
+
+        xer_file.write_text(SAMPLE_XER_SINGLE_PROJECT)
+
+        result = await load_xer(file_path=str(xer_file), db_path="")
+
+        assert result["success"] is True
+        expected_db = str(tmp_path / "my_schedule.sqlite")
+        assert result["database"]["db_path"] == expected_db
+        assert result["database"]["is_persistent"] is True
+        assert Path(expected_db).exists()
+
+    async def test_load_xer_without_db_path_uses_memory(
+        self, sample_xer_single_project: Path
+    ) -> None:
+        """load_xer without db_path uses in-memory database (backward compatible)."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        result = await load_xer(file_path=str(sample_xer_single_project))
+
+        assert result["success"] is True
+        assert result["database"]["db_path"] == ":memory:"
+        assert result["database"]["is_persistent"] is False
+
+    async def test_load_xer_database_contains_all_data(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """Persistent database contains all parsed data."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        # Verify data via direct SQL
+        conn = sqlite3.connect(str(db_file))
+        cursor = conn.execute("SELECT COUNT(*) FROM activities")
+        count = cursor.fetchone()[0]
+        conn.close()
+
+        assert count == result["activity_count"]
+
+    async def test_load_xer_response_includes_database_info(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """load_xer response includes complete database info."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        assert "database" in result
+        db_info = result["database"]
+        assert "db_path" in db_info
+        assert "is_persistent" in db_info
+        assert "source_file" in db_info
+        assert "loaded_at" in db_info
+        assert "schema" in db_info
+
+    async def test_load_xer_response_schema_includes_tables(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """load_xer response schema includes table information."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        schema = result["database"]["schema"]
+        assert "version" in schema
+        assert "tables" in schema
+        table_names = [t["name"] for t in schema["tables"]]
+        assert "activities" in table_names
+        assert "relationships" in table_names
+
+    async def test_load_xer_error_on_invalid_path(self, sample_xer_single_project: Path) -> None:
+        """load_xer returns error for invalid path."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path="/nonexistent/dir/file.db",
+        )
+
+        assert result["success"] is False
+        # Either FILE_NOT_WRITABLE or DATABASE_ERROR is acceptable
+        # depending on how SQLite reports the error
+        assert result["error"]["code"] in ("FILE_NOT_WRITABLE", "DATABASE_ERROR")
+
+
+class TestLoadXerToolSchema:
+    """Tests for MCP tool schema."""
+
+    async def test_load_xer_tool_schema_includes_db_path(self) -> None:
+        """MCP tool schema includes db_path parameter."""
+        from xer_mcp.server import list_tools
+
+        tools = await list_tools()
+        load_xer_tool = next(t for t in tools if t.name == "load_xer")
+        props = load_xer_tool.inputSchema["properties"]
+        assert "db_path" in props
+        assert props["db_path"]["type"] == "string"
--- a/tests/integration/test_direct_db_access.py
+++ b/tests/integration/test_direct_db_access.py
@@ -0,0 +1,185 @@
+"""Integration tests for direct database access feature."""
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from xer_mcp.db import db
+
+
+@pytest.fixture(autouse=True)
+def setup_db():
+    """Reset database state for each test."""
+    if db.is_initialized:
+        db.close()
+    yield
+    if db.is_initialized:
+        db.close()
+
+
+class TestDirectDatabaseAccess:
+    """Integration tests verifying external script can access database."""
+
+    async def test_external_script_can_query_database(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """External script can query database using returned path."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        # Simulate external script access (as shown in quickstart.md)
+        db_path = result["database"]["db_path"]
+
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+
+        # Query milestones
+        cursor = conn.execute("""
+            SELECT task_code, task_name, target_start_date, milestone_type
+            FROM activities
+            WHERE task_type IN ('TT_Mile', 'TT_FinMile')
+            ORDER BY target_start_date
+        """)
+
+        milestones = cursor.fetchall()
+        conn.close()
+
+        assert len(milestones) > 0
+        assert all(row["task_code"] for row in milestones)
+
+    async def test_external_script_can_query_critical_path(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """External script can query critical path activities."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        db_path = result["database"]["db_path"]
+
+        conn = sqlite3.connect(db_path)
+        cursor = conn.execute("""
+            SELECT task_code, task_name, target_start_date, target_end_date
+            FROM activities
+            WHERE driving_path_flag = 1
+            ORDER BY target_start_date
+        """)
+
+        critical_activities = cursor.fetchall()
+        conn.close()
+
+        assert len(critical_activities) > 0
+
+    async def test_external_script_can_join_tables(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """External script can join activities with WBS."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        db_path = result["database"]["db_path"]
+
+        conn = sqlite3.connect(db_path)
+        cursor = conn.execute("""
+            SELECT a.task_code, a.task_name, w.wbs_name
+            FROM activities a
+            JOIN wbs w ON a.wbs_id = w.wbs_id
+            LIMIT 10
+        """)
+
+        joined_rows = cursor.fetchall()
+        conn.close()
+
+        assert len(joined_rows) > 0
+
+    async def test_database_accessible_after_mcp_load(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """Database remains accessible while MCP tools are active."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+        loaded_count = result["activity_count"]
+
+        # External script queries database
+        conn = sqlite3.connect(str(db_file))
+        cursor = conn.execute("SELECT COUNT(*) FROM activities")
+        external_count = cursor.fetchone()[0]
+        conn.close()
+
+        # Both should match
+        assert external_count == loaded_count
+
+    async def test_schema_info_matches_actual_database(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """Returned schema info matches actual database structure."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        schema = result["database"]["schema"]
+        db_path = result["database"]["db_path"]
+
+        # Verify tables exist in actual database
+        conn = sqlite3.connect(db_path)
+        cursor = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+        )
+        actual_tables = {row[0] for row in cursor.fetchall()}
+        conn.close()
+
+        schema_tables = {t["name"] for t in schema["tables"]}
+        assert schema_tables == actual_tables
+
+    async def test_row_counts_match_actual_data(
+        self, tmp_path: Path, sample_xer_single_project: Path
+    ) -> None:
+        """Schema row counts match actual database row counts."""
+        from xer_mcp.tools.load_xer import load_xer
+
+        db_file = tmp_path / "schedule.db"
+        result = await load_xer(
+            file_path=str(sample_xer_single_project),
+            db_path=str(db_file),
+        )
+
+        schema = result["database"]["schema"]
+        db_path = result["database"]["db_path"]
+
+        conn = sqlite3.connect(db_path)
+
+        for table_info in schema["tables"]:
+            cursor = conn.execute(
+                f"SELECT COUNT(*) FROM {table_info['name']}"  # noqa: S608
+            )
+            actual_count = cursor.fetchone()[0]
+            assert table_info["row_count"] == actual_count, (
+                f"Table {table_info['name']}: expected {table_info['row_count']}, "
+                f"got {actual_count}"
+            )
+
+        conn.close()
--- a/tests/unit/test_db_manager.py
+++ b/tests/unit/test_db_manager.py
@@ -0,0 +1,234 @@
+"""Unit tests for DatabaseManager file-based database support."""
+
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+
+from xer_mcp.db import DatabaseManager
+
+
+class TestDatabaseManagerInitialization:
+    """Tests for DatabaseManager initialization modes."""
+
+    def test_initialize_with_memory_by_default(self) -> None:
+        """Default initialization uses in-memory database."""
+        dm = DatabaseManager()
+        dm.initialize()
+        assert dm.db_path == ":memory:"
+        assert dm.is_persistent is False
+        dm.close()
+
+    def test_initialize_with_file_path(self, tmp_path: Path) -> None:
+        """Can initialize with explicit file path."""
+        db_file = tmp_path / "test.db"
+        dm = DatabaseManager()
+        dm.initialize(db_path=str(db_file))
+        assert dm.db_path == str(db_file)
+        assert dm.is_persistent is True
+        assert db_file.exists()
+        dm.close()
+
+    def test_initialize_with_empty_string_auto_generates_path(self, tmp_path: Path) -> None:
+        """Empty string db_path with source_file auto-generates path."""
+        xer_file = tmp_path / "schedule.xer"
+        xer_file.write_text("dummy content")
+
+        dm = DatabaseManager()
+        dm.initialize(db_path="", source_file=str(xer_file))
+        expected_db = str(tmp_path / "schedule.sqlite")
+        assert dm.db_path == expected_db
+        assert dm.is_persistent is True
+        assert Path(expected_db).exists()
+        dm.close()
+
+    def test_file_database_persists_after_close(self, tmp_path: Path) -> None:
+        """File-based database persists after connection close."""
+        db_file = tmp_path / "persist_test.db"
+        dm = DatabaseManager()
+        dm.initialize(db_path=str(db_file))
+
+        # Insert test data
+        with dm.cursor() as cur:
+            cur.execute(
+                "INSERT INTO projects (proj_id, proj_short_name, loaded_at) "
+                "VALUES ('P1', 'Test', datetime('now'))"
+            )
+        dm.commit()
+        dm.close()
+
+        # Verify file exists and has data
+        assert db_file.exists()
+        conn = sqlite3.connect(str(db_file))
+        cursor = conn.execute("SELECT proj_id FROM projects")
+        rows = cursor.fetchall()
+        conn.close()
+        assert len(rows) == 1
+        assert rows[0][0] == "P1"
+
+    def test_source_file_tracked(self, tmp_path: Path) -> None:
+        """Source file path is tracked when provided."""
+        db_file = tmp_path / "test.db"
+        xer_file = tmp_path / "schedule.xer"
+        xer_file.write_text("dummy")
+
+        dm = DatabaseManager()
+        dm.initialize(db_path=str(db_file), source_file=str(xer_file))
+        assert dm.source_file == str(xer_file)
+        dm.close()
+
+    def test_loaded_at_timestamp(self, tmp_path: Path) -> None:
+        """Loaded_at timestamp is recorded."""
+        db_file = tmp_path / "test.db"
+        dm = DatabaseManager()
+        before = datetime.now()
+        dm.initialize(db_path=str(db_file))
+        after = datetime.now()
+
+        loaded_at = dm.loaded_at
+        assert loaded_at is not None
+        assert before <= loaded_at <= after
+        dm.close()
+
+    def test_memory_database_not_persistent(self) -> None:
+        """In-memory database is not persistent."""
+        dm = DatabaseManager()
+        dm.initialize()
+        assert dm.is_persistent is False
+        assert dm.db_path == ":memory:"
+        dm.close()
+
+
+class TestDatabaseManagerWalMode:
+    """Tests for WAL mode in file-based databases."""
+
+    def test_file_database_uses_wal_mode(self, tmp_path: Path) -> None:
+        """File-based database uses WAL mode for concurrent access."""
+        db_file = tmp_path / "wal_test.db"
+        dm = DatabaseManager()
+        dm.initialize(db_path=str(db_file))
+
+        with dm.cursor() as cur:
+            cur.execute("PRAGMA journal_mode")
+            mode = cur.fetchone()[0]
+        assert mode.lower() == "wal"
+        dm.close()
+
+    def test_memory_database_does_not_use_wal(self) -> None:
+        """In-memory database doesn't use WAL mode (not applicable)."""
+        dm = DatabaseManager()
+        dm.initialize()
+
+        with dm.cursor() as cur:
+            cur.execute("PRAGMA journal_mode")
+            mode = cur.fetchone()[0]
+        # Memory databases use 'memory' journal mode
+        assert mode.lower() == "memory"
+        dm.close()
+
+
+class TestAtomicWrite:
+    """Tests for atomic write pattern."""
+
+    def test_atomic_write_creates_final_file(self, tmp_path: Path) -> None:
+        """Database is created at final path after initialization."""
+        target = tmp_path / "atomic_test.db"
+        dm = DatabaseManager()
+        dm.initialize(db_path=str(target))
+        assert target.exists()
+        assert not Path(str(target) + ".tmp").exists()
+        dm.close()
+
+    def test_atomic_write_no_temp_file_remains(self, tmp_path: Path) -> None:
+        """No .tmp file remains after successful initialization."""
+        target = tmp_path / "atomic_clean.db"
+        dm = DatabaseManager()
+        dm.initialize(db_path=str(target))
+        dm.close()
+
+        # Check no temp files remain
+        temp_files = list(tmp_path.glob("*.tmp"))
+        assert len(temp_files) == 0
+
+
+class TestSchemaIntrospection:
+    """Tests for database schema introspection."""
+
+    def test_get_schema_info_returns_all_tables(self) -> None:
+        """Schema info includes all database tables."""
+        dm = DatabaseManager()
+        dm.initialize()
+        schema = dm.get_schema_info()
+
+        assert schema["version"] == "0.2.0"
+        table_names = [t["name"] for t in schema["tables"]]
+        assert "projects" in table_names
+        assert "activities" in table_names
+        assert "relationships" in table_names
+        assert "wbs" in table_names
+        assert "calendars" in table_names
+        dm.close()
+
+    def test_get_schema_info_includes_column_details(self) -> None:
+        """Schema info includes column names, types, and nullable."""
+        dm = DatabaseManager()
+        dm.initialize()
+        schema = dm.get_schema_info()
+
+        activities_table = next(t for t in schema["tables"] if t["name"] == "activities")
+        column_names = [c["name"] for c in activities_table["columns"]]
+        assert "task_id" in column_names
+        assert "task_name" in column_names
+
+        # Check column details
+        task_id_col = next(c for c in activities_table["columns"] if c["name"] == "task_id")
+        assert task_id_col["type"] == "TEXT"
+        # Note: SQLite reports PRIMARY KEY TEXT columns as nullable
+        # but the PRIMARY KEY constraint still applies
+        assert "nullable" in task_id_col
+
+        # Check a NOT NULL column
+        task_name_col = next(c for c in activities_table["columns"] if c["name"] == "task_name")
+        assert task_name_col["nullable"] is False
+        dm.close()
+
+    def test_get_schema_info_includes_row_counts(self) -> None:
+        """Schema info includes row counts for each table."""
+        dm = DatabaseManager()
+        dm.initialize()
+        schema = dm.get_schema_info()
+
+        for table in schema["tables"]:
+            assert "row_count" in table
+            assert isinstance(table["row_count"], int)
+            assert table["row_count"] >= 0
+        dm.close()
+
+    def test_schema_info_includes_primary_keys(self) -> None:
+        """Schema info includes primary key for each table."""
+        dm = DatabaseManager()
+        dm.initialize()
+        schema = dm.get_schema_info()
+
+        activities_table = next(t for t in schema["tables"] if t["name"] == "activities")
+        assert "primary_key" in activities_table
+        assert "task_id" in activities_table["primary_key"]
+        dm.close()
+
+    def test_schema_info_includes_foreign_keys(self) -> None:
+        """Schema info includes foreign key relationships."""
+        dm = DatabaseManager()
+        dm.initialize()
+        schema = dm.get_schema_info()
+
+        activities_table = next(t for t in schema["tables"] if t["name"] == "activities")
+        assert "foreign_keys" in activities_table
+
+        # activities.proj_id -> projects.proj_id
+        fk = next(
+            (fk for fk in activities_table["foreign_keys"] if fk["column"] == "proj_id"),
+            None,
+        )
+        assert fk is not None
+        assert fk["references_table"] == "projects"
+        assert fk["references_column"] == "proj_id"
+        dm.close()
--- a/tests/unit/test_table_handlers.py
+++ b/tests/unit/test_table_handlers.py
@@ -157,6 +157,147 @@ class TestTaskHandler:
        assert result["early_start_date"] is None
        assert result["early_end_date"] is None

+    def test_parse_milestone_type_start(self) -> None:
+        """Handler should parse milestone_type='start' for start milestones."""
+        from xer_mcp.parser.table_handlers.task import TaskHandler
+
+        handler = TaskHandler()
+
+        fields = [
+            "task_id",
+            "proj_id",
+            "task_code",
+            "task_name",
+            "task_type",
+            "milestone_type",
+        ]
+        values = [
+            "2001",
+            "1001",
+            "MS-START",
+            "Project Start",
+            "TT_Mile",
+            "MS_Start",
+        ]
+
+        result = handler.parse_row(fields, values)
+
+        assert result is not None
+        assert result["task_type"] == "TT_Mile"
+        assert result["milestone_type"] == "start"
+
+    def test_parse_milestone_type_finish(self) -> None:
+        """Handler should parse milestone_type='finish' for finish milestones."""
+        from xer_mcp.parser.table_handlers.task import TaskHandler
+
+        handler = TaskHandler()
+
+        fields = [
+            "task_id",
+            "proj_id",
+            "task_code",
+            "task_name",
+            "task_type",
+            "milestone_type",
+        ]
+        values = [
+            "2002",
+            "1001",
+            "MS-END",
+            "Project Complete",
+            "TT_Mile",
+            "MS_Finish",
+        ]
+
+        result = handler.parse_row(fields, values)
+
+        assert result is not None
+        assert result["task_type"] == "TT_Mile"
+        assert result["milestone_type"] == "finish"
+
+    def test_parse_milestone_type_null_for_non_milestones(self) -> None:
+        """Handler should return None for milestone_type on non-milestone activities."""
+        from xer_mcp.parser.table_handlers.task import TaskHandler
+
+        handler = TaskHandler()
+
+        fields = [
+            "task_id",
+            "proj_id",
+            "task_code",
+            "task_name",
+            "task_type",
+        ]
+        values = [
+            "2003",
+            "1001",
+            "A1000",
+            "Regular Task",
+            "TT_Task",
+        ]
+
+        result = handler.parse_row(fields, values)
+
+        assert result is not None
+        assert result["task_type"] == "TT_Task"
+        assert result["milestone_type"] is None
+
+    def test_parse_milestone_type_derived_from_tt_mile(self) -> None:
+        """Handler should derive milestone_type='start' from task_type TT_Mile."""
+        from xer_mcp.parser.table_handlers.task import TaskHandler
+
+        handler = TaskHandler()
+
+        # No explicit milestone_type field - derive from task_type
+        fields = [
+            "task_id",
+            "proj_id",
+            "task_code",
+            "task_name",
+            "task_type",
+        ]
+        values = [
+            "2001",
+            "1001",
+            "MS-START",
+            "Project Start",
+            "TT_Mile",
+        ]
+
+        result = handler.parse_row(fields, values)
+
+        assert result is not None
+        assert result["task_type"] == "TT_Mile"
+        assert result["milestone_type"] == "start"
+
+    def test_parse_milestone_type_derived_from_tt_finmile(self) -> None:
+        """Handler should derive milestone_type='finish' from task_type TT_FinMile."""
+        from xer_mcp.parser.table_handlers.task import TaskHandler
+
+        handler = TaskHandler()
+
+        # TT_FinMile is a finish milestone
+        fields = [
+            "task_id",
+            "proj_id",
+            "task_code",
+            "task_name",
+            "task_type",
+        ]
+        values = [
+            "2002",
+            "1001",
+            "MS-END",
+            "Project Complete",
+            "TT_FinMile",
+        ]
+
+        result = handler.parse_row(fields, values)
+
+        assert result is not None
+        assert result["task_type"] == "TT_FinMile"
+        assert result["milestone_type"] == "finish"
+

 class TestTaskpredHandler:
    """Tests for TASKPRED table handler."""
--- a/uv.lock
+++ b/uv.lock
@@ -578,7 +578,7 @@ wheels = [

 [[package]]
 name = "xer-mcp"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
    { name = "mcp" },
Author	SHA1	Message	Date
Bill Ballou	f57fc14162	Merge branch '002-direct-db-access': Direct database access for scripts (v0.2.0)	2026-01-08 13:02:07 -05:00
Bill Ballou	05ffc3793c	docs: update CLAUDE.md and bump version to 0.2.0 - Add persistent SQLite database to active technologies - Update recent changes section for 002-direct-db-access - Bump package version to 0.2.0 in uv.lock	2026-01-08 13:01:49 -05:00
Bill Ballou	e250cc7444	docs: mark all tasks as complete in tasks.md	2026-01-08 12:56:29 -05:00
Bill Ballou	d6a79bf24a	feat: add direct database access for scripts (v0.2.0) Implement persistent SQLite database feature that allows scripts to query schedule data directly via SQL after loading XER files through MCP. Key changes: - Extend load_xer with db_path parameter for persistent database - Add get_database_info tool to retrieve database connection details - Add schema introspection with tables, columns, primary/foreign keys - Support WAL mode for concurrent read access - Use atomic write pattern to prevent corruption New features: - db_path=None: in-memory database (default, backward compatible) - db_path="": auto-generate path from XER filename (.sqlite extension) - db_path="/path/to/db": explicit persistent database path Response includes complete DatabaseInfo: - db_path: absolute path (or :memory:) - is_persistent: boolean - source_file: loaded XER path - loaded_at: ISO timestamp - schema: tables with columns, primary keys, foreign keys, row counts Closes: User Story 1, 2, 3 from 002-direct-db-access spec	2026-01-08 12:54:56 -05:00
Bill Ballou	3e7ad39eb8	docs: add specification and implementation plan for direct database access feature This feature (002-direct-db-access) enables scripts to query schedule data directly via SQL after loading XER files through MCP. Key additions: - spec.md: Feature specification with 3 user stories - plan.md: Implementation plan with constitution check - research.md: Technology decisions (SQLite file, WAL mode, atomic writes) - data-model.md: DatabaseInfo, SchemaInfo, TableInfo entities - contracts/mcp-tools.json: Extended load_xer schema, new get_database_info tool - quickstart.md: Usage examples for direct database access - tasks.md: 16 implementation tasks across 6 phases	2026-01-08 12:38:42 -05:00
Bill Ballou	48628fd30e	Merge branch '001-schedule-tools' # Conflicts: # README.md	2026-01-08 12:22:53 -05:00
Bill Ballou	a7b6b76db8	feat: add milestone_type field to distinguish start/finish milestones Add milestone_type field to milestone queries that indicates whether a milestone is a start milestone ('start') or finish milestone ('finish'). Changes: - Add milestone_type column to activities table schema - Parse milestone_type from XER TASK table (MS_Start/MS_Finish) - Include milestone_type in list_milestones response - Update contract tests for milestone_type field - Update specs, contracts, and documentation The milestone_type is determined by: 1. Explicit milestone_type field in XER (MS_Start -> 'start', MS_Finish -> 'finish') 2. Derived from task_type (TT_Mile -> 'start', TT_FinMile -> 'finish')	2026-01-08 12:18:34 -05:00
Bill Ballou	bf2f85813e	fix: include finish milestones (TT_FinMile) in milestone queries The list_milestones tool was only returning start milestones (TT_Mile) and missing all finish milestones. P6 uses two task types for milestones: - TT_Mile = Start Milestone - TT_FinMile = Finish Milestone Changes: - Update query_milestones() to include both TT_Mile and TT_FinMile - Derive milestone_type from task_type when not explicitly set: - TT_Mile -> 'start' - TT_FinMile -> 'finish' - Add unit tests for milestone_type derivation from task_type This fixes the E-J Electric schedule returning 5 milestones instead of 62.	2026-01-08 11:55:43 -05:00
Bill	a6413eaaae	Initial commit	2026-01-06 21:31:07 -05:00