Estado de fase (MASTER-00): POST_MVP — documento de catálogo de producto sujeto a validación; no es alcance aprobado de Gate 0 / PoC / MVP. Gobernanza: MASTER-00.

DocuGraph Master Testing & Traceability Plan

1. OVERVIEW & TEST OBJECTIVES

1.1 Purpose of the Master Test Plan

The DocuGraph Master Testing & Traceability Plan defines the comprehensive quality assurance framework, verification strategy, test execution environments, test fixtures, and 100% end-to-end traceability matrix for DocuGraph v0.01.

DocuGraph is an AI-assisted atomic documentation editor and dependency graph system spanning four Kotlin Multiplatform (KMP) monorepo modules (:docugraph-core, :docugraph-app, :docugraph-mcp, :docugraph-backend). This document guarantees that every user story (US-01 to US-06), interaction flow (IX-01 to IX-04), UI composable (FE-01 to FE-05), backend task (BE-01 to BE-06), OpenAPI operationId (loginUser, createProject, buildGraph, getTaskContext, validateTraceability, checkEntitlement), relational database table (users, subscriptions, projects, nodes, node_edges, mcp_api_keys), and MCP server feature is systematically validated prior to release.

1.2 Quality Goals & Acceptance Thresholds

100% Documentation Traceability: Zero broken relative links, zero orphan document nodes, and zero cyclic dependency errors across all 34 monorepo documentation files.
$>85\%$ Code Coverage: Minimum 85% line coverage and 90% branch coverage across :docugraph-core and :docugraph-backend modules.
$<150$ ms MCP Task Context Latency: Maximum 150 ms execution window for reverse topological graph traversal and context bundle assembly in :docugraph-mcp.
60 FPS Viewport Rendering: Uninterrupted 60 FPS frame rate during canvas pan/zoom interactions over graphs with up to 1,000 nodes and 2,500 edges in :docugraph-app.
Zero Hallucination AI Task Context: 100% accurate, non-overflowing context bundle extraction for AI coding agents.

2. 4-TIER TEST STRATEGY SPECIFICATION

The quality assurance strategy is structured into four complementary verification tiers:

+-----------------------------------------------------------------------------------+
|                            4-Tier Test Strategy Hierarchy                         |
+-----------------------------------------------------------------------------------+

[ Tier 4: Real-World Applications  ] ---> Self-Ingestion, AI Coding Agent Stdio Execution
[ Tier 3: Cross-Feature E2E Flows  ] ---> 5 End-to-End User & Agent Workflow Sequences
[ Tier 2: Boundary & Corner Cases  ] ---> 15 Failure Scenarios (Cycles, Quotas, Limits)
[ Tier 1: Feature Unit & Module    ] ---> Unit & Integration Tests per KMP Module

2.1 Tier 1: Feature Coverage (Unit & Module Integration)

Tier 1 tests focus on verifying isolated business logic, data models, Ktor REST endpoints, Compose composables, and MCP handlers in isolation across all four monorepo modules:

Target Module	Component / Package	Test Type	Specific Test Objectives	Primary Assertion / Pass Criteria
`:docugraph-core`	`YamlFrontmatterParser`	Unit	Parse valid YAML frontmatter header blocks from Markdown files	Correctly extracts `id`, `title`, `type`, `status`, `tags`, `links` maps
`:docugraph-core`	`GraphEngine`	Unit	Construct directed graph, perform topological sort, and detect cycles via Tarjan's SCC	Returns sorted node list for DAG; throws `CycleDetectedException` for loops
`:docugraph-core`	`LinkValidator`	Unit	Audit relative Markdown links and ID references against graph index	Returns zero broken links for valid references; reports exact line numbers for broken links
`:docugraph-backend`	`AuthService` (`BE-01`)	Integration	Verify email/password against Argon2id hash; issue signed RS256 JWT access/refresh tokens	Returns HTTP 200 with valid JWT containing `user_id` and `entitlement_id` claims
`:docugraph-backend`	`ProjectService` (`BE-02`)	Integration	Register workspace directory, enforce project quota (3 max for Free tier), and parse files	Returns HTTP 201 with project UUID; returns HTTP 403 when 4th project is created by Free tier user
`:docugraph-backend`	`GraphService` (`BE-03`)	Integration	Query PostgreSQL `nodes` and `node_edges` tables to build adjacency JSON payload	Returns HTTP 200 with `total_nodes`, `total_edges`, and adjacency arrays
`:docugraph-backend`	`McpContextService` (`BE-04`)	Integration	Perform reverse topological traversal up to `maxDepth`; enforce `effectiveMaxDepth=2` for Free tier	Returns compiled Markdown bundle; sets `truncated=true` and `effectiveMaxDepth=2` for Free tier
`:docugraph-backend`	`AuditService` (`BE-05`)	Integration	Run full workspace audit, calculate `health_score`, detect cycles and missing `operationId`s	Returns HTTP 200 with `health_score` (0.0 - 100.0) and error item arrays
`:docugraph-backend`	`EntitlementService` (`BE-06`)	Integration	Query RevenueCat REST API v1 for user entitlement status with offline grace limit fallback	Returns HTTP 200 with `is_pro`, `max_projects_allowed`, and `offline_grace_until`
`:docugraph-app`	`LoginForm` (`FE-01`)	UI Unit	Render email/password inputs, validate email format, display error state on HTTP 401	UI state transitions to `Loading` -> `Error` when invalid credentials are submitted
`:docugraph-app`	`ProjectDashboard` (`FE-02`)	UI Unit	Display project cards, search filter, and "Create Project" modal button	Correctly filters project list in real time; opens modal on click
`:docugraph-app`	`GraphCanvas` (`FE-03`)	UI Unit	Render interactive node-edge graph canvas, handle pan/zoom gestures and node selection	Renders node boxes and directed arrow paths; emits `onNodeSelected(nodeId)` event
`:docugraph-app`	`NodeInspector` (`FE-04`)	UI Unit	Render drawer showing node frontmatter, dependencies, and markdown preview	Displays upstream/downstream links; updates drawer content when selection changes
`:docugraph-app`	`PaywallModal` (`FE-05`)	UI Unit	Render RevenueCat Pro subscription tiers, price comparison, and "Upgrade Now" button	Launches platform native purchase flow on click; closes modal on success
`:docugraph-mcp`	`McpResourceHandler`	Integration	Resolve `docugraph://workspace/nodes`, `/graph`, `/node/{id}`, `/audit-report` URIs	Returns JSON or text/markdown payload matching specified schema
`:docugraph-mcp`	`McpToolHandler`	Integration	Dispatch JSON-RPC tool calls (`get_task_context`, `get_dependency_graph`, `validate_traceability`)	Returns formatted tool execution results within 150ms execution window
`:docugraph-mcp`	`McpPromptHandler`	Integration	Render prompt templates (`prompt_implement_task`, `prompt_audit_traceability`)	Returns system prompt message array containing injected task context

2.2 Tier 2: Boundary, Edge & Failure Corner Cases

Tier 2 tests evaluate robust error handling, stress limits, corrupted file recovery, and quota limit enforcement through 15 specific edge test cases:

Malformed & Corrupted Frontmatter:
TC-EDGE-01: Parse Markdown file missing closing --- frontmatter delimiter. Verification: Core engine catches parse exception, flags exact line number, and continues scanning without crashing workspace.
TC-EDGE-02: Frontmatter missing mandatory top-level key (id). Verification: Audit engine records INVALID_FRONTMATTER error and excludes node from graph indexing.
TC-EDGE-03: Frontmatter containing invalid YAML syntax (unquoted special characters, illegal indentation). Verification: Core parser emits detailed diagnostic error with line and column offsets.
Graph Topology & Cycle Boundary Conditions:
TC-EDGE-04: Direct 2-node cycle (US-01 links to US-02, US-02 links to US-01). Verification: Tarjan's SCC algorithm identifies cycle path [US-01, US-02, US-01] and flags it in circular_dependencies.
TC-EDGE-05: Complex 5-node indirect cycle (A -> B -> C -> D -> E -> B). Verification: Cycle detection isolates exact loop sub-path without dropping independent graph branches.
TC-EDGE-06: Empty workspace directory containing 0 Markdown files. Verification: System returns empty graph with total_nodes: 0, total_edges: 0, and health_score: 100.0.
TC-EDGE-07: Deeply nested linear graph tree ($>50$ levels deep). Verification: Reverse topological traversal handles depth recursion without encountering StackOverflowError.
Data Volume & Performance Limits:
TC-EDGE-08: Large Markdown node ($>10,000$ lines of content, $>2$ MB file size). Verification: AST parsing completes in $<200$ ms; memory allocation remains bounded.
TC-EDGE-09: Large project workspace containing 10,000 atomic nodes and 30,000 edges. Verification: buildGraph completes in $<500$ ms using indexed PostgreSQL query.
Quota, Subscription & Entitlement Limits:
TC-EDGE-10: Free tier user attempting to create a 4th project. Verification: Backend returns HTTP 403 Forbidden with error code PROJECT_LIMIT_EXCEEDED and triggers FE-05 PaywallModal.
TC-EDGE-11: Free tier user requesting get_task_context with maxDepth = 10. Verification: System caps effectiveMaxDepth at 2, sets truncated = true, and appends upgrade notice to markdown bundle.
TC-EDGE-12: Active user operating offline after 8 days ($>7$ days offline grace limit). Verification: System degrades entitlement to Free tier capabilities until online sync succeeds.
Security, Network & Transport Failures:
TC-EDGE-13: Request with invalid or expired RS256 JWT access token. Verification: Backend returns HTTP 401 Unauthorized with EXPIRED_TOKEN code.
TC-EDGE-14: MCP JSON-RPC tool call with invalid API Key (X-MCP-API-KEY). Verification: MCP server rejects connection with JSON-RPC error code -32001 (Unauthorized).
TC-EDGE-15: Abrupt network termination during HTTP SSE transport stream. Verification: MCP server cleanly releases connection resources without memory leaks.

2.3 Tier 3: Cross-Feature End-to-End Integration Flows

Tier 3 verifies end-to-end user and AI agent journeys across multiple monorepo layers:

+-----------------------------------------------------------------------------------+
|                        Tier 3 Integration Workflow Sequences                      |
+-----------------------------------------------------------------------------------+

Flow 1: User Login & Session Persistence
[FE-01 LoginForm] ---> POST /api/v1/auth/login ---> [BE-01 Auth Task] ---> (table: users)
                                                                      ---> Returns JWT + Entitlement

Flow 2: Workspace Project Ingestion & Graph Indexing
[FE-02 Dashboard] ---> POST /api/v1/projects ---> [BE-02 Project Task] ---> [:docugraph-core Parser]
                                                                         ---> Persists (projects, nodes, edges)

Flow 3: Interactive Canvas Visualizer & Node Inspector
[FE-03 GraphCanvas] ---> GET /api/v1/projects/{id}/graph ---> [BE-03 Graph Task] ---> Returns Adjacency JSON
  |
  +---> Click Node ---> [FE-04 NodeInspector] ---> GET docugraph://workspace/node/{id}

Flow 4: AI Agent Context Bundle Extraction & Quota Enforcement
[AI Coding Agent] ---> Stdio / SSE JSON-RPC ---> [MCP get_task_context] ---> [BE-04 Task Context]
                                                                          ---> Checks [BE-06 Entitlement]
                                                                          ---> Returns Context Bundle

Flow 5: Automated Traceability & Graph Health Audit
[FE-03 / MCP Client] ---> POST /api/v1/mcp/validate-traceability ---> [BE-05 Audit Task]
                                                                   ---> Runs Tarjan SCC & Link Checker
                                                                   ---> Returns Audit Report

Workflow E2E-01: Authentication & Session Management:
User inputs credentials in FE-01 LoginForm -> IX-01 flow triggers BE-01 auth.login (loginUser operationId) -> Password verified against table: users Argon2id hash -> Session token and entitlement_id fetched from table: subscriptions -> Returns RS256 JWT -> LoginForm transitions to ProjectDashboard.
Workflow E2E-02: Project Creation & Local Workspace Indexing:
User submits local directory path in FE-02 ProjectDashboard -> IX-02 flow invokes BE-02 project.create (createProject operationId) -> Entitlement limit verified against table: subscriptions -> :docugraph-core scans workspace directory, parses YAML frontmatters, generates AST nodes and directed edges -> Records written to table: projects, table: nodes, and table: node_edges -> Success response returned.
Workflow E2E-03: Interactive Graph Canvas Inspection:
Client requests project graph -> IX-03 flow invokes BE-03 graph.build (buildGraph operationId) -> Queries table: nodes and table: node_edges -> Returns GraphDataResponse JSON -> FE-03 GraphCanvas renders interactive node-edge layout -> User selects node US-04 -> FE-04 NodeInspector fetches detail via docugraph://workspace/node/US-04 resource -> Displays YAML frontmatter and upstream dependencies.
Workflow E2E-04: AI Agent Task Context Bundle Extraction & Quota Gating:
AI coding agent (Claude Code / Cursor) connects via Stdio transport to :docugraph-mcp -> Invokes get_task_context(taskId = "US-04", maxDepth = 5) tool -> IX-04 flow delegates to BE-04 mcp.get_task_context (getTaskContext operationId) -> Backend checks user entitlement via BE-06 checkEntitlement (table: subscriptions) -> For Free tier, caps effectiveMaxDepth = 2 -> Performs reverse topological traversal in :docugraph-core -> Assembles single combined Markdown bundle -> Returns bundle to AI agent in $<150$ ms.
Workflow E2E-05: Graph Traceability & Integrity Audit:
User or AI agent invokes validate_traceability tool -> Delegates to BE-05 mcp.validate_traceability (validateTraceability operationId) -> Backend executes Tarjan's SCC algorithm to detect cycles, audits relative links against table: nodes, and verifies OpenAPI operationId references -> Returns AuditReportResponse containing health_score: 100.0, zero cycles, and zero broken links -> FE-03 GraphCanvas renders clean state.

2.4 Tier 4: Real-World Application & AI Agent Integration Scenarios

Tier 4 verifies system stability and usability under actual production development environments:

Scenario REAL-01: Self-Ingestion of DocuGraph Monorepo Documentation:
Description: Ingest and index DocuGraph's own 34 documentation specification files (docs/00_BUSINESS_VISION.md through docs/testing/TEST-01_verification-plan.md).
Expected Outcome: System parses all 34 files without errors, constructs DAG with 34 nodes and directed dependency edges, achieves a 100% health_score, and detects zero cyclic dependencies.
Scenario REAL-02: Microservice Architecture DAG Ingestion:
Description: Ingest an enterprise microservice project containing 500 atomic specification nodes, 1,200 cross-service API edges, 50 database tables, and 100 interaction flows.
Expected Outcome: Graph building completes in $<350$ ms; canvas pan/zoom maintains 60 FPS in FE-03 GraphCanvas; topological sort completes in $<50$ ms.
Scenario REAL-03: AI Coding Agent (Claude Code / Cursor CLI) Task Execution via Stdio:
Description: An AI coding agent is assigned task BE-04. The agent invokes prompt_implement_task(taskId = "BE-04"), receives the auto-assembled context bundle (containing BE-04, US-04, IX-04, SCHEMA-01, and openapi.yaml), and generates the implementation code.
Expected Outcome: The AI agent receives exact context without context window truncation or overflow, eliminating hallucinations and producing code satisfying 100% of specification requirements.
Scenario REAL-04: Multi-Agent Remote IDE Collaboration via HTTP SSE Transport:
Description: Multiple remote AI agents and developer web IDEs connect concurrently to :docugraph-mcp over HTTP SSE transport (/mcp/sse).
Expected Outcome: MCP server handles concurrent JSON-RPC requests smoothly, maintains isolated session contexts, and streams graph mutation events in real time.

3. TEST EXECUTION ENVIRONMENTS & FIXTURES

3.1 Standardized Test Fixture Inventory

Six standardized test fixtures are maintained in test-fixtures/ for repeatable automated execution:

Fixture FIX-01: valid_atomic_workspace: A clean, standardized monorepo directory containing 10 Markdown files with valid YAML frontmatter, valid relative links, valid OpenAPI operationId references, and a perfect DAG topology.
Fixture FIX-02: corrupted_frontmatter_workspace: A collection of Markdown files featuring broken YAML syntax, unclosed frontmatter delimiters (---), missing mandatory id fields, non-string tags, and malformed link maps.
Fixture FIX-03: cyclic_dependency_workspace: Test workspace containing intentional dependency loops:
Direct 2-node cycle: NODE-A -> NODE-B -> NODE-A
Complex 4-node cycle: NODE-W -> NODE-X -> NODE-Y -> NODE-Z -> NODE-X
Fixture FIX-04: database_seed_dataset: SQL seed script for PostgreSQL containing pre-populated test records:
2 Test Users (1 Free tier user, 1 Pro tier user)
2 Subscriptions (Free active, Pro active with RevenueCat customer IDs)
3 Projects with pre-computed node and edge records
2 Active MCP API Keys (mcp_key_free_123, mcp_key_pro_987)
Fixture FIX-05: mock_revenuecat_server: WireMock / Ktor mock server simulating RevenueCat REST API v1 responses:
200 OK with active pro_tier entitlement
200 OK with free tier entitlement
404 Not Found for un-subscribed customer IDs
503 Service Unavailable to test offline grace period logic
Fixture FIX-06: mcp_stdio_jsonrpc_harness: A lightweight Kotlin test harness that launches :docugraph-mcp as a subprocess, sends standard JSON-RPC 2.0 requests over stdin, and parses stdout responses.

3.2 Test Execution Environments

+------------------------------------------------------------------------------------+
|                         Test Execution Environment Architecture                    |
+------------------------------------------------------------------------------------+

1. Local JVM Engine: `./gradlew test`
   - Runs unit tests for `:docugraph-core` (YamlFrontmatterParser, GraphEngine, Tarjan SCC)

2. Ktor Embedded Server: `io.ktor.server.testing.testApplication`
   - Runs integration tests for `:docugraph-backend` REST endpoints (/api/v1/*)

3. PostgreSQL Testcontainers: `org.testcontainers.containers.PostgreSQLContainer`
   - Provides ephemeral PostgreSQL database for schema DDL and query verification

4. Compose UI Test Framework: `androidx.compose.ui.test.junit4`
   - Runs UI unit tests for `:docugraph-app` composables (FE-01 .. FE-05)

5. MCP Stdio / SSE Test Runner: Subprocess JSON-RPC client
   - Verifies `:docugraph-mcp` resources, tools, and prompts compliance

4. AUTOMATED VERIFICATION CASES & TEST HARNESS SPECIFICATIONS

4.1 Automated Verification Command (`validate_traceability`)

The system provides an automated traceability verification script (validate_traceability) executable via CLI or MCP tool call:

# Command Line Execution Example
./gradlew runTraceabilityAudit --workspace=/path/to/docugraph/docs --output=json

Verification Formula & Rules:

Frontmatter Audit: Validates YAML frontmatter presence, syntax, and mandatory keys (id, title, type, status, tags, links).
Orphan Node Audit: Verifies every node ID appears in at least one upstream depends_on or downstream depended_by list (excluding root README).
OpenAPI OperationId Audit: Scans all BE-XX specs and interaction flows; verifies cited operationIds exist in docs/api/openapi.yaml.
Database Table Reference Audit: Verifies tables: [XXX] links reference valid tables in docs/domain/01_DATABASE_SCHEMA.md.
Cycle Detection Audit: Executes Tarjan's SCC algorithm; returns cycle path list if cycles exist.
Health Score Calculation: Computes normalized score (0.0 to 100.0) based on weighted penalty deductions: $$\text{Health Score} = 100.0 - (5.0 \times \text{Cycles}) - (2.0 \times \text{Broken Links}) - (1.0 \times \text{Missing OpIDs})$$

5. COMPLETE 34-FILE END-TO-END TRACEABILITY MATRIX

The following comprehensive matrix maps all 34 monorepo documentation files listed in docs/01_PROJECT_MANIFEST.md to their respective project phases, milestones, system components, assigned test suites, verification methods, and integrity audit rules:

#	File Path	Frontmatter ID	Title	Phase	Milestone	System Component	Primary Test Suite / Case ID	Verification Method	Traceability & Integrity Rule
1	`README.md`	`README`	System Overview & Quickstart	Phase 0	M1	Root Workspace	`TS-CORE-01` (`TC-READ-01`)	Static Audit & Link Checker	Root node; depended_by `VISION-00`, `MANIFEST-01`
2	`AGENTS.md`	`AGENTS`	AI Agent Guidelines & Protocols	Phase 0	M1	Root Workspace	`TS-MCP-01` (`TC-AGENT-01`)	Static Audit & Prompt Spec	Guidelines node; depended_by `VISION-00`, `MANIFEST-01`
3	`docs/00_BUSINESS_VISION.md`	`VISION-00`	Business Vision & Monetization	Phase 1	M1	System Strategy	`TS-BIZ-01` (`TC-VIS-01`)	Static Audit & Schema Check	Depends on `README`; depended_by `US-01`..`US-06`
4	`docs/user_stories/US-01_login.md`	`US-01`	Authentication User Story	Phase 1	M1	Auth Subsystem	`TS-E2E-01` (`TC-US01-01`)	Tier 3 E2E Integration Flow 1	Maps to `IX-01`, `FE-01`, `BE-01`, `loginUser`, `users`
5	`docs/user_stories/US-02_create_project.md`	`US-02`	Project Creation User Story	Phase 1	M1	Project Subsystem	`TS-E2E-02` (`TC-US02-01`)	Tier 3 E2E Integration Flow 2	Maps to `IX-02`, `FE-02`, `BE-02`, `createProject`, `projects`
6	`docs/user_stories/US-03_view_graph.md`	`US-03`	Interactive Canvas User Story	Phase 1	M1	Graph Visualizer	`TS-E2E-03` (`TC-US03-01`)	Tier 3 E2E Integration Flow 3	Maps to `IX-03`, `FE-03`, `FE-04`, `BE-03`, `buildGraph`
7	`docs/user_stories/US-04_get_task_context.md`	`US-04`	Task Context Extraction User Story	Phase 1	M1	MCP Protocol Engine	`TS-E2E-04` (`TC-US04-01`)	Tier 3 E2E Integration Flow 4	Maps to `IX-04`, `FE-04`, `BE-04`, `getTaskContext`
8	`docs/user_stories/US-05_validate_traceability.md`	`US-05`	Traceability Audit User Story	Phase 1	M1	Audit Subsystem	`TS-E2E-05` (`TC-US05-01`)	Tier 3 E2E Integration Flow 5	Maps to `IX-03`, `FE-03`, `BE-05`, `validateTraceability`
9	`docs/user_stories/US-06_revenuecat_pro.md`	`US-06`	Subscription Pro User Story	Phase 1	M1	Billing Subsystem	`TS-E2E-06` (`TC-US06-01`)	Tier 3 E2E Integration Flow 4	Maps to `IX-01`, `IX-04`, `FE-05`, `BE-06`, `checkEntitlement`
10	`docs/01_PROJECT_MANIFEST.md`	`MANIFEST-01`	System Manifest & Matrix	Phase 2	M2	System Index	`TS-CORE-02` (`TC-MAN-01`)	Programmatic Audit (`validate`)	Authoritative index of all 34 files
11	`docs/02_GLOBAL_SPEC.md`	`GLOBAL-02`	Global Specification	Phase 2	M2	Architecture Spec	`TS-CORE-02` (`TC-GLOB-01`)	Static Audit & Constraint Check	Defines product scope boundaries (in-scope / out-of-scope)
12	`docs/03_ARCHITECTURE.md`	`ARCH-03`	Monorepo System Architecture	Phase 2	M2	Architecture Spec	`TS-CORE-02` (`TC-ARCH-01`)	Static Audit & Dataflow Check	System architecture & module data flow sequences
13	`docs/domain/01_DATABASE_SCHEMA.md`	`SCHEMA-01`	PostgreSQL Relational Schema	Phase 2	M2	Data Architecture	`TS-DB-01` (`TC-SCH-01`)	Testcontainers DDL Execution	Defines 6 relational tables; depended_by BE & IX specs
14	`docs/domain/02_GLOSSARY.md`	`GLOSSARY-01`	Domain Glossary & Taxonomy	Phase 2	M2	Domain Taxonomy	`TS-CORE-02` (`TC-GLOS-01`)	Static Audit & Term Checker	Defines taxonomy (nodes, edges, frontmatter, DAG)
15	`docs/interaction/IX-01_login-flow.md`	`IX-01`	Login Interaction Flow Spec	Phase 2.5	M2	Auth Interaction	`TS-UI-01` (`TC-IX01-01`)	Tier 1 UI & Integration	Maps `US-01` to `FE-01` & `BE-01`; references `loginUser`
16	`docs/interaction/IX-02_create-edit-project-flow.md`	`IX-02`	Project Creation Flow Spec	Phase 2.5	M2	Project Interaction	`TS-UI-02` (`TC-IX02-01`)	Tier 1 UI & Integration	Maps `US-02` to `FE-02` & `BE-02`; references `createProject`
17	`docs/interaction/IX-03_graph-inspection-flow.md`	`IX-03`	Graph Inspection Flow Spec	Phase 2.5	M2	Visualizer Interaction	`TS-UI-03` (`TC-IX03-01`)	Tier 1 UI & Integration	Maps `US-03`/`US-05` to `FE-03`/`FE-04`/`BE-03`/`BE-05`
18	`docs/interaction/IX-04_mcp-context-bundle-flow.md`	`IX-04`	MCP Context Extraction Flow Spec	Phase 2.5	M2	MCP Interaction	`TS-UI-04` (`TC-IX04-01`)	Tier 1 UI & Integration	Maps `US-04`/`US-06` to `FE-04`/`FE-05`/`BE-04`/`BE-06`
19	`docs/api/openapi.yaml`	`API-OPENAPI`	REST OpenAPI 3.1.0 Contract	Phase 3	M3	REST API Contract	`TS-API-01` (`TC-API-01`)	OpenAPI Swagger Validator	Single source of truth for 6 REST `operationId`s
20	`docs/backend/BE-01_auth-login.md`	`BE-01`	Backend Spec: `auth.login`	Phase 3	M3	`:docugraph-backend`	`TS-BE-01` (`TC-BE01-01`)	Ktor Test Application	Maps to `loginUser`, `table: users`, `table: subscriptions`
21	`docs/backend/BE-02_project-create.md`	`BE-02`	Backend Spec: `project.create`	Phase 3	M3	`:docugraph-backend`	`TS-BE-02` (`TC-BE02-01`)	Ktor Test Application	Maps to `createProject`, `table: projects`, `table: users`
22	`docs/backend/BE-03_graph-build.md`	`BE-03`	Backend Spec: `graph.build`	Phase 3	M3	`:docugraph-backend`	`TS-BE-03` (`TC-BE03-01`)	Ktor Test Application	Maps to `buildGraph`, `table: nodes`, `table: node_edges`
23	`docs/backend/BE-04_mcp-get-task-context.md`	`BE-04`	Backend Spec: `mcp.get_task_context`	Phase 3	M3	`:docugraph-backend`	`TS-BE-04` (`TC-BE04-01`)	Ktor Test Application	Maps to `getTaskContext`, `table: nodes`, `table: subscriptions`
24	`docs/backend/BE-05_mcp-validate-traceability.md`	`BE-05`	Backend Spec: `mcp.validate_traceability`	Phase 3	M3	`:docugraph-backend`	`TS-BE-05` (`TC-BE05-01`)	Ktor Test Application	Maps to `validateTraceability`, Tarjan's SCC algorithm
25	`docs/backend/BE-06_paywall-check-entitlement.md`	`BE-06`	Backend Spec: `paywall.check_entitlement`	Phase 3	M3	`:docugraph-backend`	`TS-BE-06` (`TC-BE06-01`)	Ktor Test Application	Maps to `checkEntitlement`, RevenueCat API v1 mock
26	`docs/frontend/FE-01_login-form.md`	`FE-01`	Frontend Component Spec: `LoginForm`	Phase 3	M3	`:docugraph-app`	`TS-FE-01` (`TC-FE01-01`)	Compose UI Test Framework	Renders login UI; maps to `IX-01` & `BE-01`
27	`docs/frontend/FE-02_project-dashboard.md`	`FE-02`	Frontend Component Spec: `ProjectDashboard`	Phase 3	M3	`:docugraph-app`	`TS-FE-02` (`TC-FE02-01`)	Compose UI Test Framework	Renders project grid; maps to `IX-02` & `BE-02`
28	`docs/frontend/FE-03_graph-canvas.md`	`FE-03`	Frontend Component Spec: `GraphCanvas`	Phase 3	M3	`:docugraph-app`	`TS-FE-03` (`TC-FE03-01`)	Compose UI Test Framework	Renders DAG canvas; maps to `IX-03` & `BE-03`
29	`docs/frontend/FE-04_node-inspector.md`	`FE-04`	Frontend Component Spec: `NodeInspector`	Phase 3	M3	`:docugraph-app`	`TS-FE-04` (`TC-FE04-01`)	Compose UI Test Framework	Renders node drawer; maps to `IX-03`/`IX-04` & `BE-04`
30	`docs/frontend/FE-05_paywall-modal.md`	`FE-05`	Frontend Component Spec: `PaywallModal`	Phase 3	M3	`:docugraph-app`	`TS-FE-05` (`TC-FE05-01`)	Compose UI Test Framework	Renders Pro paywall; maps to `IX-04` & `BE-06`
31	`docs/mcp/MCP_SPEC.md`	`MCP-SPEC`	Kotlin MCP Server Protocol Spec	Phase 3	M3	`:docugraph-mcp`	`TS-MCP-01` (`TC-MCP-01`)	Stdio/SSE JSON-RPC Harness	Defines resources, tools (`get_task_context`), prompts
32	`docs/srs/SRS_IEEE-830.md`	`SRS-830`	System Requirements Spec (IEEE 830)	Phase 4	M4	System Specification	`TS-SRS-01` (`TC-SRS-01`)	Static Audit & Requirements Check	SRS IEEE 830 specification document
33	`docs/project_plan/PLAN-01_delivery-plan.md`	`PLAN-01`	Master Project Plan & Spikes	Phase 4	M4	Project Management	`TS-PLAN-01` (`TC-PLN-01`)	Milestone Verification	Project plan, spikes, delivery schedule, risk matrix
34	`docs/testing/TEST-01_verification-plan.md`	`TEST-01`	Master Testing & Verification Plan	Phase 4	M4	Quality Assurance	`TS-TEST-01` (`TC-TST-01`)	Self-Verification & Audit Run	Master test plan & 34-file traceability matrix

6. TEST EXECUTION & REPORTING PIPELINE

6.1 CI/CD Automation Workflow

All 4 test tiers are automated within GitHub Actions workflows executing across a matrix of operating systems:

# GitHub Actions Test Pipeline Architecture
name: DocuGraph Master Verification Suite

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  tier-1-unit-and-integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'
      - name: Run Core Unit & Ktor Integration Tests
        run: ./gradlew test --all

  tier-2-and-3-e2e-suite:
    needs: tier-1-unit-and-integration
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: docugraph_test
          POSTGRES_USER: docugraph
          POSTGRES_PASSWORD: test_password
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v3
      - name: Run E2E Integration Suite & MCP Harness
        run: ./gradlew runE2ETests

  tier-4-traceability-audit:
    needs: tier-2-and-3-e2e-suite
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Execute Workspace Traceability Audit
        run: ./gradlew runTraceabilityAudit --workspace=docs --output=json

6.2 Quality Gates & Release Thresholds

Pre-Commit Gate: validate_traceability must return health_score = 100.0 with zero broken links or circular dependencies.
Pull Request Gate: Tier 1 and Tier 2 tests must pass with $>85\%$ line coverage across modified packages.
Release Gate: 100% pass rate across Tier 1, Tier 2, Tier 3, and Tier 4 test suites on Android, iOS, Desktop JVM, and Web Wasm build targets.

7. TRACEABILITY INDEX

Upstream Dependencies:
docs/01_PROJECT_MANIFEST.md (MANIFEST-01)
docs/02_GLOBAL_SPEC.md (GLOBAL-02)
docs/03_ARCHITECTURE.md (ARCH-03)
docs/domain/01_DATABASE_SCHEMA.md (SCHEMA-01)
docs/srs/SRS_IEEE-830.md (SRS-830)
docs/project_plan/PLAN-01_delivery-plan.md (PLAN-01)
Downstream Artifacts:
None (Terminal Milestone M4 Quality Assurance Artifact)